import { Meta, Canvas, Primary, Controls, Title, Description } from "@storybook/addon-docs/blocks";

import * as stories from "./breadcrumbs.stories";

<Meta of={stories} />

```ts
import { BreadcrumbsModule } from "@bitwarden/components";
```

<Title />
<Description />

<Primary />
<Controls />

## Usage

The breadcrumb component is used to indicate the user's current location in a hierarchical structure
of pages.

Breadcrumbs are typically paired with page content to help users understand where they are within a
site or application and navigate back to parent pages.

The active breadcrumb should always be the last in the list of breadcrumbs. (See
[Breadcrumbs with Page Header](#breadcrumbs-with-page-header) for the exception case.) Note that the
stories here in Storybook do not necessarily follow that guidance, in order to provide examples of
how the active styling works with the router.

### Routes

Breadcrumbs are typically links to page content. When provided a `route`, they will render as anchor
tag links. Without a `route`, the breadcrumb will be a button element and will need a `(click)`
handler attached.

Routed breadcrumbs hook into the Angular router to add styles the active breadcrumb and display it
as static text rather than a link. Button breadcrumbs will not display an active breadcrumb since
they are not hooked into the router.

#### As buttons

<Canvas of={stories.DefaultAsButtons} />

### Sizes

Size should be chosen based on available space. Use the base size on large screen layouts where
there is ample horizontal space. Use the sm size in space-constrained contexts, such as smaller
screen widths and the extension.

#### Base size

<Canvas of={stories.Default} />

#### Small size

<Canvas of={stories.Small} />

### Overflow

When a user is several levels deep into a tree, the breadcrumbs list will truncate. Based on the
number passed to the `show` input (which defaults to 4), it will display any overflow breadcrumbs in
a menu before the last breadcrumb.

<Canvas of={stories.OverflowLinks} />

### Breadcrumbs with page header

When breadcrumbs are used within a header that displays the active page outside of the breadcrumbs
(such as in a separate heading element), use `showTrailingArrow` to display one last arrow at the
end of the breadcrumbs list. This provides better visual continuity to guide the user's eyes to the
heading element as a logical continuation of the breadcrumbs. The heading element should be placed
immediately below the breadcrumbs.

<Canvas of={stories.WithTrailingArrow} />

## Guidelines

Breadcrumb labels should reflect the exact page or section name for clarity and consistency.
