# Rokkit BreadCrumbs Component

> Navigation trail showing the current location within a hierarchy.

The BreadCrumbs component displays a path of links showing the user's location in a site hierarchy, with support for custom separators and field mapping.

## Quick Start

```svelte
<script>
  import { BreadCrumbs } from '@rokkit/ui'

  let path = [
    { label: 'Home', href: '/' },
    { label: 'Products', href: '/products' },
    { label: 'Electronics', href: '/products/electronics' },
    { label: 'Laptops' }
  ]
</script>

<BreadCrumbs items={path} />
```

## Core Concepts

### Path Structure

Each breadcrumb item represents a level in the hierarchy:

```javascript
const items = [
  { label: 'Home', href: '/' },           // Clickable link
  { label: 'Category', href: '/cat' },    // Clickable link
  { label: 'Current Page' }               // No href = current page
]
```

### Custom Separator

Change the separator between items:

```svelte
<!-- Default: / -->
<BreadCrumbs {items} />

<!-- Arrow -->
<BreadCrumbs {items} separator="→" />

<!-- Chevron icon -->
<BreadCrumbs {items} separator="chevron-right" />

<!-- Custom text -->
<BreadCrumbs {items} separator=">" />
```

### Field Mapping

Map your data structure to breadcrumb fields:

```svelte
<script>
  import { BreadCrumbs } from '@rokkit/ui'

  let navigation = [
    { label: 'Dashboard', url: '/dash' },
    { label: 'Settings', url: '/settings' },
    { label: 'Profile' }
  ]

  const fields = {
    text: 'label',
    href: 'url'
  }
</script>

<BreadCrumbs items={navigation} {fields} />
```

### Custom Item Rendering

Use the `child` snippet for custom rendering:

```svelte
<BreadCrumbs {items}>
  {#snippet child(proxy)}
    {#if proxy.has('href')}
      <a href={proxy.get('href')} class="custom-crumb">
        {proxy.get('text')}
      </a>
    {:else}
      <span class="current-crumb">{proxy.get('text')}</span>
    {/if}
  {/snippet}
</BreadCrumbs>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `array` | `[]` | Breadcrumb items |
| `separator` | `string` | `'/'` | Separator between items |
| `fields` | `object` | `{}` | Field mapping configuration |
| `child` | `Snippet` | `undefined` | Custom item renderer |
| `class` | `string` | `''` | CSS class names |

## Field Mapping

| Field | Default | Description |
|-------|---------|-------------|
| `text` | `'text'` | Display text |
| `href` | `'href'` | Link URL |
| `icon` | `'icon'` | Optional icon |

## Component Structure

```
<div data-crumb-root>
├── <div data-crumb-item>           // First item
│   └── <Item>                      // Rendered via Item component
├── <Icon data-crumb-separator>     // Separator
├── <div data-crumb-item>           // Second item
│   └── <Item>
├── <Icon data-crumb-separator>
└── <div data-crumb-item is-selected> // Last item (current)
    └── <Item>
</div>
```

## Data Attributes for Styling

| Attribute | Element | Purpose |
|-----------|---------|---------|
| `data-crumb-root` | Root | Main container |
| `data-crumb-item` | div | Individual crumb |
| `data-crumb-separator` | Icon | Separator element |
| `.is-selected` | Last item | Current page indicator |

### Styling Example

```css
[data-crumb-root] {
  display: flex;
  align-items: center;
  gap: 8px;
  font-size: 0.875rem;
}

[data-crumb-item] {
  display: flex;
  align-items: center;
}

[data-crumb-item] a {
  color: var(--primary-600);
  text-decoration: none;
}

[data-crumb-item] a:hover {
  text-decoration: underline;
}

[data-crumb-item].is-selected {
  color: var(--text-primary);
  font-weight: 500;
}

[data-crumb-separator] {
  color: var(--text-muted);
  font-size: 0.75rem;
}
```

## Import

```javascript
// Named import
import { BreadCrumbs } from '@rokkit/ui'

// Default import
import BreadCrumbs from '@rokkit/ui/bread-crumbs'
```

## TypeScript Types

```typescript
interface BreadCrumbsProps {
  items?: BreadCrumbItem[]
  separator?: string
  fields?: FieldMapping
  child?: Snippet<[Proxy]>
  class?: string
}

interface BreadCrumbItem {
  text?: string
  href?: string
  icon?: string
  [key: string]: any
}
```

## Examples

### Basic Breadcrumbs

```svelte
<script>
  import { BreadCrumbs } from '@rokkit/ui'

  let crumbs = [
    { label: 'Home', href: '/' },
    { label: 'Blog', href: '/blog' },
    { label: 'Article Title' }
  ]
</script>

<BreadCrumbs items={crumbs} />
```

### With Icons

```svelte
<script>
  import { BreadCrumbs } from '@rokkit/ui'

  let crumbs = [
    { label: 'Home', href: '/', icon: 'home' },
    { label: 'Settings', href: '/settings', icon: 'cog' },
    { label: 'Profile', icon: 'user' }
  ]
</script>

<BreadCrumbs items={crumbs} />
```

### Arrow Separator

```svelte
<script>
  import { BreadCrumbs } from '@rokkit/ui'

  let path = [
    { label: 'Dashboard', href: '/dash' },
    { label: 'Reports', href: '/reports' },
    { label: 'Sales Report' }
  ]
</script>

<BreadCrumbs items={path} separator="→" />
```

### Chevron Separator

```svelte
<script>
  import { BreadCrumbs } from '@rokkit/ui'

  let path = [
    { label: 'Shop', href: '/shop' },
    { label: 'Clothing', href: '/shop/clothing' },
    { label: 'T-Shirts' }
  ]
</script>

<BreadCrumbs items={path} separator="chevron-right" />
```

### Dynamic Path from URL

```svelte
<script>
  import { BreadCrumbs } from '@rokkit/ui'
  import { page } from '$app/stores'

  let crumbs = $derived.by(() => {
    const segments = $page.url.pathname.split('/').filter(Boolean)
    return [
      { label: 'Home', href: '/' },
      ...segments.map((segment, i) => ({
        text: segment.charAt(0).toUpperCase() + segment.slice(1),
        href: '/' + segments.slice(0, i + 1).join('/'),
        // Last item has no href
        ...(i === segments.length - 1 ? { href: undefined } : {})
      }))
    ]
  })
</script>

<BreadCrumbs items={crumbs} />
```

### With Custom Rendering

```svelte
<script>
  import { BreadCrumbs } from '@rokkit/ui'

  let crumbs = [
    { label: 'Home', href: '/', icon: 'home' },
    { label: 'Products', href: '/products', count: 42 },
    { label: 'Widget Pro' }
  ]
</script>

<BreadCrumbs items={crumbs}>
  {#snippet child(proxy)}
    <div class="crumb-content">
      {#if proxy.has('icon')}
        <i class={proxy.get('icon')}></i>
      {/if}

      {#if proxy.has('href')}
        <a href={proxy.get('href')}>{proxy.get('text')}</a>
      {:else}
        <span>{proxy.get('text')}</span>
      {/if}

      {#if proxy.value.count}
        <span class="count">({proxy.value.count})</span>
      {/if}
    </div>
  {/snippet}
</BreadCrumbs>
```

### E-commerce Path

```svelte
<script>
  import { BreadCrumbs } from '@rokkit/ui'

  let productPath = [
    { label: 'Home', href: '/' },
    { label: 'Electronics', href: '/electronics' },
    { label: 'Computers', href: '/electronics/computers' },
    { label: 'Laptops', href: '/electronics/computers/laptops' },
    { label: 'MacBook Pro 16"' }
  ]
</script>

<nav aria-label="Breadcrumb">
  <BreadCrumbs items={productPath} separator="/" />
</nav>
```

### Truncated Breadcrumbs

```svelte
<script>
  import { BreadCrumbs } from '@rokkit/ui'

  let longPath = [
    { label: 'Home', href: '/' },
    { label: 'Documents', href: '/docs' },
    { label: 'Projects', href: '/docs/projects' },
    { label: '2024', href: '/docs/projects/2024' },
    { label: 'Q1', href: '/docs/projects/2024/q1' },
    { label: 'Report.pdf' }
  ]

  // Show first, ellipsis, last 2
  let displayPath = $derived([
    longPath[0],
    { label: '...', href: undefined },
    ...longPath.slice(-2)
  ])
</script>

<BreadCrumbs items={displayPath} />
```

## Accessibility

- Wrap in `<nav aria-label="Breadcrumb">` for screen readers
- Current page (last item) should not be a link
- Use semantic separators (visual only, not announced)

```svelte
<nav aria-label="Breadcrumb">
  <BreadCrumbs {items} />
</nav>
```

## Related Components

- **PageNavigator** - Page navigation with prev/next
- **Stepper** - Step-based progress navigation
- **Tabs** - Tab-based navigation