From 5b3c8b2f1607c7ad887d1cff3ae08c133c9a7b0e Mon Sep 17 00:00:00 2001
From: HHamude <homsi.hamude@gmail.com>
Date: Tue, 18 Jul 2023 12:07:09 +0300
Subject: [PATCH] feat(breadcrumb): add new `bq-breadcrumb` component (#266)

---
 packages/bee-q/src/components.d.ts            | 106 +++++++++++++
 .../__tests__/bq-breadcrumb-item.e2e.ts       |  48 ++++++
 .../breadcrumb-item/bq-breadcrumb-item.tsx    | 139 ++++++++++++++++++
 .../src/components/breadcrumb-item/readme.md  |  40 +++++
 .../scss/bq-breadcrumb-item.scss              |  21 +++
 .../scss/bq-breadcrumb-item.variables.scss    |  43 ++++++
 .../breadcrumb/__tests__/bq-breadcrumb.e2e.ts | 101 +++++++++++++
 .../breadcrumb/_storybook/bq-breadcrumb.mdx   |  39 +++++
 .../_storybook/bq-breadcrumb.stories.tsx      |  95 ++++++++++++
 .../components/breadcrumb/bq-breadcrumb.tsx   | 131 +++++++++++++++++
 .../bee-q/src/components/breadcrumb/readme.md |  33 +++++
 .../breadcrumb/scss/bq-breadcrumb.scss        |   7 +
 12 files changed, 803 insertions(+)
 create mode 100644 packages/bee-q/src/components/breadcrumb-item/__tests__/bq-breadcrumb-item.e2e.ts
 create mode 100644 packages/bee-q/src/components/breadcrumb-item/bq-breadcrumb-item.tsx
 create mode 100644 packages/bee-q/src/components/breadcrumb-item/readme.md
 create mode 100644 packages/bee-q/src/components/breadcrumb-item/scss/bq-breadcrumb-item.scss
 create mode 100644 packages/bee-q/src/components/breadcrumb-item/scss/bq-breadcrumb-item.variables.scss
 create mode 100644 packages/bee-q/src/components/breadcrumb/__tests__/bq-breadcrumb.e2e.ts
 create mode 100644 packages/bee-q/src/components/breadcrumb/_storybook/bq-breadcrumb.mdx
 create mode 100644 packages/bee-q/src/components/breadcrumb/_storybook/bq-breadcrumb.stories.tsx
 create mode 100644 packages/bee-q/src/components/breadcrumb/bq-breadcrumb.tsx
 create mode 100644 packages/bee-q/src/components/breadcrumb/readme.md
 create mode 100644 packages/bee-q/src/components/breadcrumb/scss/bq-breadcrumb.scss

diff --git a/packages/bee-q/src/components.d.ts b/packages/bee-q/src/components.d.ts
index b6451dbe4..caeb3683d 100644
--- a/packages/bee-q/src/components.d.ts
+++ b/packages/bee-q/src/components.d.ts
@@ -81,6 +81,34 @@ export namespace Components {
          */
         "textColor"?: string;
     }
+    interface BqBreadcrumb {
+        /**
+          * The `aria-label` attribute to describe the type of navigation
+         */
+        "ariaLabel": string;
+    }
+    interface BqBreadcrumbItem {
+        /**
+          * The aria-label that corresponds to the full title of the destination page. This won't be shown in the page, but it will be used by screen readers and other assistive devices.
+         */
+        "ariaLabel": string;
+        /**
+          * If set, the breadcrumb item will be rendered as an `<a>` with this `href`, otherwise, a `<button>` will be rendered.
+         */
+        "href": string;
+        /**
+          * If true, the item is the last element inside breadcrumb
+         */
+        "isLastItem": boolean;
+        /**
+          * Where to display the link in the browser context. Relevant only if `href` is set.
+         */
+        "rel": string;
+        /**
+          * Where to display the link in the browser context. Relevant only if `href` is set.
+         */
+        "target": '_blank' | '_parent' | '_self' | '_top';
+    }
     /**
      * Buttons are designed for users to take action on a page or a screen.
      */
@@ -660,6 +688,14 @@ export namespace Components {
         "visible"?: boolean;
     }
 }
+export interface BqBreadcrumbCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLBqBreadcrumbElement;
+}
+export interface BqBreadcrumbItemCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLBqBreadcrumbItemElement;
+}
 export interface BqButtonCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLBqButtonElement;
@@ -732,6 +768,18 @@ declare global {
         prototype: HTMLBqBadgeElement;
         new (): HTMLBqBadgeElement;
     };
+    interface HTMLBqBreadcrumbElement extends Components.BqBreadcrumb, HTMLStencilElement {
+    }
+    var HTMLBqBreadcrumbElement: {
+        prototype: HTMLBqBreadcrumbElement;
+        new (): HTMLBqBreadcrumbElement;
+    };
+    interface HTMLBqBreadcrumbItemElement extends Components.BqBreadcrumbItem, HTMLStencilElement {
+    }
+    var HTMLBqBreadcrumbItemElement: {
+        prototype: HTMLBqBreadcrumbItemElement;
+        new (): HTMLBqBreadcrumbItemElement;
+    };
     /**
      * Buttons are designed for users to take action on a page or a screen.
      */
@@ -856,6 +904,8 @@ declare global {
     interface HTMLElementTagNameMap {
         "bq-avatar": HTMLBqAvatarElement;
         "bq-badge": HTMLBqBadgeElement;
+        "bq-breadcrumb": HTMLBqBreadcrumbElement;
+        "bq-breadcrumb-item": HTMLBqBreadcrumbItemElement;
         "bq-button": HTMLBqButtonElement;
         "bq-checkbox": HTMLBqCheckboxElement;
         "bq-dialog": HTMLBqDialogElement;
@@ -920,6 +970,58 @@ declare namespace LocalJSX {
          */
         "textColor"?: string;
     }
+    interface BqBreadcrumb {
+        /**
+          * The `aria-label` attribute to describe the type of navigation
+         */
+        "ariaLabel"?: string;
+        /**
+          * Handler to be called when `bq-breadcrumb-item` item loses focus.
+         */
+        "onBqBreadcrumbBlur"?: (event: BqBreadcrumbCustomEvent<HTMLBqBreadcrumbItemElement>) => void;
+        /**
+          * Handler to be called when `bq-breadcrumb-item` is selected (on click/enter press).
+         */
+        "onBqBreadcrumbClick"?: (event: BqBreadcrumbCustomEvent<HTMLBqBreadcrumbItemElement>) => void;
+        /**
+          * Handler to be called when `bq-breadcrumb-item` item gets focus.
+         */
+        "onBqBreadcrumbFocus"?: (event: BqBreadcrumbCustomEvent<HTMLBqBreadcrumbItemElement>) => void;
+    }
+    interface BqBreadcrumbItem {
+        /**
+          * The aria-label that corresponds to the full title of the destination page. This won't be shown in the page, but it will be used by screen readers and other assistive devices.
+         */
+        "ariaLabel"?: string;
+        /**
+          * If set, the breadcrumb item will be rendered as an `<a>` with this `href`, otherwise, a `<button>` will be rendered.
+         */
+        "href"?: string;
+        /**
+          * If true, the item is the last element inside breadcrumb
+         */
+        "isLastItem"?: boolean;
+        /**
+          * Handler to be called when item loses focus
+         */
+        "onBqBlur"?: (event: BqBreadcrumbItemCustomEvent<HTMLBqBreadcrumbItemElement>) => void;
+        /**
+          * Handler to be called when item is clicked
+         */
+        "onBqClick"?: (event: BqBreadcrumbItemCustomEvent<HTMLBqBreadcrumbItemElement>) => void;
+        /**
+          * Handler to be called when item is focused
+         */
+        "onBqFocus"?: (event: BqBreadcrumbItemCustomEvent<HTMLBqBreadcrumbItemElement>) => void;
+        /**
+          * Where to display the link in the browser context. Relevant only if `href` is set.
+         */
+        "rel"?: string;
+        /**
+          * Where to display the link in the browser context. Relevant only if `href` is set.
+         */
+        "target"?: '_blank' | '_parent' | '_self' | '_top';
+    }
     /**
      * Buttons are designed for users to take action on a page or a screen.
      */
@@ -1549,6 +1651,8 @@ declare namespace LocalJSX {
     interface IntrinsicElements {
         "bq-avatar": BqAvatar;
         "bq-badge": BqBadge;
+        "bq-breadcrumb": BqBreadcrumb;
+        "bq-breadcrumb-item": BqBreadcrumbItem;
         "bq-button": BqButton;
         "bq-checkbox": BqCheckbox;
         "bq-dialog": BqDialog;
@@ -1578,6 +1682,8 @@ declare module "@stencil/core" {
              */
             "bq-avatar": LocalJSX.BqAvatar & JSXBase.HTMLAttributes<HTMLBqAvatarElement>;
             "bq-badge": LocalJSX.BqBadge & JSXBase.HTMLAttributes<HTMLBqBadgeElement>;
+            "bq-breadcrumb": LocalJSX.BqBreadcrumb & JSXBase.HTMLAttributes<HTMLBqBreadcrumbElement>;
+            "bq-breadcrumb-item": LocalJSX.BqBreadcrumbItem & JSXBase.HTMLAttributes<HTMLBqBreadcrumbItemElement>;
             /**
              * Buttons are designed for users to take action on a page or a screen.
              */
diff --git a/packages/bee-q/src/components/breadcrumb-item/__tests__/bq-breadcrumb-item.e2e.ts b/packages/bee-q/src/components/breadcrumb-item/__tests__/bq-breadcrumb-item.e2e.ts
new file mode 100644
index 000000000..0a37bc6ae
--- /dev/null
+++ b/packages/bee-q/src/components/breadcrumb-item/__tests__/bq-breadcrumb-item.e2e.ts
@@ -0,0 +1,48 @@
+import { newE2EPage } from '@stencil/core/testing';
+
+describe('bq-breadcrumb-item', () => {
+  it('should render', async () => {
+    const page = await newE2EPage();
+    await page.setContent('<bq-breadcrumb-item></bq-breadcrumb-item>');
+
+    const element = await page.find('bq-breadcrumb-item');
+
+    expect(element).toHaveClass('hydrated');
+  });
+
+  it('should have shadow root', async () => {
+    const page = await newE2EPage();
+    await page.setContent('<bq-breadcrumb-item></bq-breadcrumb-item>');
+
+    const element = await page.find('bq-breadcrumb-item');
+
+    expect(element.shadowRoot).not.toBeNull();
+  });
+
+  it('should display text', async () => {
+    const page = await newE2EPage();
+    await page.setContent('<bq-breadcrumb-item>Home</bq-breadcrumb-item>');
+
+    const element = await page.find('bq-breadcrumb-item');
+
+    expect(element).toEqualText('Home');
+  });
+
+  it('should render `button` tag', async () => {
+    const page = await newE2EPage();
+    await page.setContent('<bq-breadcrumb-item>Home</bq-breadcrumb-item>');
+
+    const element = await page.find('bq-breadcrumb-item >>> .breadcrumb-item');
+
+    expect(element.tagName.toLocaleLowerCase()).toBe('button');
+  });
+
+  it('should render `a` tag', async () => {
+    const page = await newE2EPage();
+    await page.setContent('<bq-breadcrumb-item href="https://example.com/">Home</bq-breadcrumb-item>');
+
+    const element = await page.find('bq-breadcrumb-item >>> .breadcrumb-item');
+
+    expect(element.tagName.toLocaleLowerCase()).toBe('a');
+  });
+});
diff --git a/packages/bee-q/src/components/breadcrumb-item/bq-breadcrumb-item.tsx b/packages/bee-q/src/components/breadcrumb-item/bq-breadcrumb-item.tsx
new file mode 100644
index 000000000..cbb30c208
--- /dev/null
+++ b/packages/bee-q/src/components/breadcrumb-item/bq-breadcrumb-item.tsx
@@ -0,0 +1,139 @@
+import { h, Component, Prop, Element, Event, EventEmitter } from '@stencil/core';
+
+import { isDefined } from '../../shared/utils';
+
+/**
+ * @part base - The component wrapper container
+ * @part base - The breadcrumb item wrapper (`button` or `a`)
+ * @part content - The `span` tag that loads the content item
+ * @part separator - The `span` tag that loads the separator
+ */
+@Component({
+  tag: 'bq-breadcrumb-item',
+  styleUrl: './scss/bq-breadcrumb-item.scss',
+  shadow: true,
+})
+export class BqBreadcrumbItem {
+  // Own Properties
+  // ====================
+
+  // Reference to host HTML element
+  // ===================================
+
+  @Element() el!: HTMLBqBreadcrumbItemElement;
+
+  // State() variables
+  // Inlined decorator, alphabetical order
+  // =======================================
+
+  // Public Property API
+  // ========================
+
+  /**
+   * The aria-label that corresponds to the full title of the destination page.
+   * This won't be shown in the page, but it will be used by screen readers and other assistive devices.
+   */
+  @Prop() ariaLabel: string;
+
+  /** If true, the item is the last element inside breadcrumb */
+  @Prop() isLastItem: boolean = false;
+
+  /** If set, the breadcrumb item will be rendered as an `<a>` with this `href`, otherwise, a `<button>` will be rendered. */
+  @Prop({ reflect: true }) href: string;
+
+  /** Where to display the link in the browser context. Relevant only if `href` is set. */
+  @Prop({ reflect: true }) target: '_blank' | '_parent' | '_self' | '_top';
+
+  /** Where to display the link in the browser context. Relevant only if `href` is set. */
+  @Prop({ reflect: true }) rel: string = 'noreferrer noopener';
+
+  // Prop lifecycle events
+  // =======================
+
+  // Events section
+  // Requires JSDocs for public API documentation
+  // ==============================================
+
+  /** Handler to be called when item loses focus */
+  @Event() bqBlur: EventEmitter<HTMLBqBreadcrumbItemElement>;
+
+  /** Handler to be called when item is focused */
+  @Event() bqFocus: EventEmitter<HTMLBqBreadcrumbItemElement>;
+
+  /** Handler to be called when item is clicked */
+  @Event() bqClick: EventEmitter<HTMLBqBreadcrumbItemElement>;
+
+  // Component lifecycle events
+  // Ordered by their natural call order
+  // =====================================
+
+  // Listeners
+  // ==============
+
+  // Public methods API
+  // These methods are exposed on the host element.
+  // Always use two lines.
+  // Public Methods must be async.
+  // Requires JSDocs for public API documentation.
+  // ===============================================
+
+  // Local methods
+  // Internal business logic.
+  // These methods cannot be called from the host element.
+  // =======================================================
+
+  private onBlur = () => {
+    this.bqBlur.emit(this.el);
+  };
+
+  private onFocus = () => {
+    this.bqFocus.emit(this.el);
+  };
+
+  private onClick = () => {
+    this.bqClick.emit(this.el);
+  };
+
+  // render() function
+  // Always the last one in the class.
+  // ===================================
+
+  render() {
+    const isLink = isDefined(this.href);
+    const TagElem = isLink ? 'a' : 'button';
+
+    return (
+      <div class="flex items-center" aria-label={this.ariaLabel} part="base">
+        <TagElem
+          class="breadcrumb-item"
+          href={isLink ? this.href : undefined}
+          rel={isLink && this.target ? 'noreferrer noopener' : undefined}
+          target={isLink ? this.target : undefined}
+          onBlur={this.onBlur}
+          onFocus={this.onFocus}
+          onClick={this.onClick}
+          aria-current={isLink && this.isLastItem ? 'location' : undefined} // indicates the last link as the current page
+          part="item"
+        >
+          <span
+            class={{
+              'flex items-center gap-xs2': true,
+              'text-text-brand': this.isLastItem,
+            }}
+            part="content"
+          >
+            <slot></slot>
+          </span>
+        </TagElem>
+        <span
+          class={{
+            'breadcrumb-separator': true,
+          }}
+          part="separator"
+        >
+          <slot name="separator"></slot>
+        </span>
+      </div>
+    );
+  }
+}
diff --git a/packages/bee-q/src/components/breadcrumb-item/readme.md b/packages/bee-q/src/components/breadcrumb-item/readme.md
new file mode 100644
index 000000000..ee82364a3
--- /dev/null
+++ b/packages/bee-q/src/components/breadcrumb-item/readme.md
@@ -0,0 +1,40 @@
+# bq-breadcrumb-item
+
+
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property     | Attribute      | Description                                                                                                                                                                    | Type                                         | Default                 |
+| ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | ----------------------- |
+| `ariaLabel`  | `aria-label`   | The aria-label that corresponds to the full title of the destination page. This won't be shown in the page, but it will be used by screen readers and other assistive devices. | `string`                                     | `undefined`             |
+| `href`       | `href`         | If set, the breadcrumb item will be rendered as an `<a>` with this `href`, otherwise, a `<button>` will be rendered.                                                           | `string`                                     | `undefined`             |
+| `isLastItem` | `is-last-item` | If true, the item is the last element inside breadcrumb                                                                                                                        | `boolean`                                    | `false`                 |
+| `rel`        | `rel`          | Where to display the link in the browser context. Relevant only if `href` is set.                                                                                              | `string`                                     | `'noreferrer noopener'` |
+| `target`     | `target`       | Where to display the link in the browser context. Relevant only if `href` is set.                                                                                              | `"_blank" \| "_parent" \| "_self" \| "_top"` | `undefined`             |
+
+
+## Events
+
+| Event     | Description                                | Type                                       |
+| --------- | ------------------------------------------ | ------------------------------------------ |
+| `bqBlur`  | Handler to be called when item loses focus | `CustomEvent<HTMLBqBreadcrumbItemElement>` |
+| `bqClick` | Handler to be called when item is clicked  | `CustomEvent<HTMLBqBreadcrumbItemElement>` |
+| `bqFocus` | Handler to be called when item is focused  | `CustomEvent<HTMLBqBreadcrumbItemElement>` |
+
+
+## Shadow Parts
+
+| Part          | Description                                |
+| ------------- | ------------------------------------------ |
+| `"base"`      | The component wrapper container            |
+| `"content"`   | The `span` tag that loads the content item |
+| `"item"`      |                                            |
+| `"separator"` | The `span` tag that loads the separator    |
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*
diff --git a/packages/bee-q/src/components/breadcrumb-item/scss/bq-breadcrumb-item.scss b/packages/bee-q/src/components/breadcrumb-item/scss/bq-breadcrumb-item.scss
new file mode 100644
index 000000000..182ff74db
--- /dev/null
+++ b/packages/bee-q/src/components/breadcrumb-item/scss/bq-breadcrumb-item.scss
@@ -0,0 +1,21 @@
+/* -------------------------------------------------------------------------- */
+/*                                Breadcrumb item styles                */
+/* -------------------------------------------------------------------------- */
+
+@import './bq-breadcrumb-item.variables';
+
+.breadcrumb-item {
+  @apply font-regular leading-[var(--bq-breadcrumb-item--line-height)] text-text-secondary no-underline focus-visible:focus active:outline-none;
+  @apply pe-[var(--bq-breadcrumb-item--padding-end)] ps-[var(--bq-breadcrumb-item--padding-start)];
+  @apply py-[var(--bq-breadcrumb-item--paddingY)] text-[length:var(--bq-breadcrumb-item--font-size)];
+  @apply rounded-[var(--bq-breadcrumb-item--border-radius)] bg-[var(--bq-breadcrumb-item--background)] shadow-[shadow:var(--bq-breadcrumb-item--box-shadow)];
+  @apply border-[length:var(--bq-breadcrumb-item--border-width)] border-[color:var(--bq-breadcrumb-item--border-color)];
+  @apply cursor-pointer hover:text-text-brand-hover;
+
+  border-style: var(--bq-avatar--border-style);
+}
+
+.breadcrumb-separator {
+  @apply flex items-center text-[length:var(--bq-breadcrumb-item--font-size-separator)];
+  @apply pe-[var(--bq-breadcrumb-item--padding-end-separator)] ps-[var(--bq-breadcrumb-item--padding-start-separator)];
+}
diff --git a/packages/bee-q/src/components/breadcrumb-item/scss/bq-breadcrumb-item.variables.scss b/packages/bee-q/src/components/breadcrumb-item/scss/bq-breadcrumb-item.variables.scss
new file mode 100644
index 000000000..a168b2364
--- /dev/null
+++ b/packages/bee-q/src/components/breadcrumb-item/scss/bq-breadcrumb-item.variables.scss
@@ -0,0 +1,43 @@
+/* -------------------------------------------------------------------------- */
+/*                          Breadcrumb item custom properties           */
+/* -------------------------------------------------------------------------- */
+
+:host {
+  /**
+  * @prop --bq-breadcrumb-item--background: background color
+  * @prop --bq-breadcrumb-item--font-size: font size
+
+  * @prop --bq-breadcrumb-item--border-color: border color
+  * @prop --bq-breadcrumb-item--border-style: border style
+  * @prop --bq-breadcrumb-item--border-width: border width
+  * @prop --bq-breadcrumb-item--border-radius: border radius
+
+  * @prop --bq-breadcrumb-item--box-shadow: box shadow
+
+  * @prop --bq-breadcrumb-item--paddingX: padding X axis
+  * @prop --bq-breadcrumb-item--paddingY: padding Y axis
+
+  * @prop --bq-breadcrumb-item--padding-separator: padding X axis on separator element
+  * @prop --bq-breadcrumb-item--font-size-separator: font size for separator
+
+  */
+
+  --bq-breadcrumb-item--background: theme('colors.transparent');
+  --bq-breadcrumb-item--font-size: theme('fontSize.s');
+  --bq-breadcrumb-item--line-height: theme('lineHeight.large');
+
+  --bq-breadcrumb-item--border-color: theme('colors.transparent');
+  --bq-breadcrumb-item--border-style: none;
+  --bq-breadcrumb-item--border-width: 0;
+  --bq-breadcrumb-item--border-radius: theme('borderRadius.s');
+
+  --bq-breadcrumb-item--box-shadow: none;
+
+  --bq-breadcrumb-item--padding-start: theme('spacing.xs2');
+  --bq-breadcrumb-item--padding-end: theme('spacing.xs2');
+  --bq-breadcrumb-item--paddingY: theme('spacing.xs');
+
+  --bq-breadcrumb-item--padding-start-separator: theme('spacing.xs2');
+  --bq-breadcrumb-item--padding-end-separator: theme('spacing.xs2');
+  --bq-breadcrumb-item--font-size-separator: theme('fontSize.xs');
+}
diff --git a/packages/bee-q/src/components/breadcrumb/__tests__/bq-breadcrumb.e2e.ts b/packages/bee-q/src/components/breadcrumb/__tests__/bq-breadcrumb.e2e.ts
new file mode 100644
index 000000000..ab13416a9
--- /dev/null
+++ b/packages/bee-q/src/components/breadcrumb/__tests__/bq-breadcrumb.e2e.ts
@@ -0,0 +1,101 @@
+import { newE2EPage } from '@stencil/core/testing';
+
+describe('bq-breadcrumb', () => {
+  it('should render', async () => {
+    const page = await newE2EPage();
+    await page.setContent('<bq-breadcrumb></bq-breadcrumb>');
+
+    const element = await page.find('bq-breadcrumb');
+
+    expect(element).toHaveClass('hydrated');
+  });
+
+  it('should have shadow root', async () => {
+    const page = await newE2EPage();
+    await page.setContent('<bq-breadcrumb></bq-breadcrumb>');
+
+    const element = await page.find('bq-breadcrumb');
+
+    expect(element.shadowRoot).not.toBeNull();
+  });
+
+  it('should trigger bqBreadcrumbClick', async () => {
+    const page = await newE2EPage();
+    await page.setContent(`
+      <bq-breadcrumb>
+        <bq-breadcrumb-item>Home</bq-breadcrumb-item>
+      </bq-breadcrumb>
+    `);
+
+    const bqBlur = await page.spyOnEvent('bqBreadcrumbBlur');
+    const bqFocus = await page.spyOnEvent('bqBreadcrumbFocus');
+    const bqClick = await page.spyOnEvent('bqBreadcrumbClick');
+
+    const element = await page.find('bq-breadcrumb-item');
+
+    await element.click();
+
+    expect(bqFocus).toHaveReceivedEventTimes(1);
+    expect(bqClick).toHaveReceivedEventTimes(1);
+    expect(bqBlur).toHaveReceivedEventTimes(0);
+  });
+
+  it('should be keyboard accessible', async () => {
+    const page = await newE2EPage();
+    await page.setContent(`
+      <bq-breadcrumb>
+        <bq-breadcrumb-item>Home</bq-breadcrumb-item>
+      </bq-breadcrumb>
+    `);
+
+    const bqBlur = await page.spyOnEvent('bqBreadcrumbBlur');
+    const bqFocus = await page.spyOnEvent('bqBreadcrumbFocus');
+    const bqClick = await page.spyOnEvent('bqBreadcrumbClick');
+
+    await page.keyboard.press('Tab');
+
+    expect(bqFocus).toHaveReceivedEventTimes(1);
+    expect(bqClick).toHaveReceivedEventTimes(0);
+    expect(bqBlur).toHaveReceivedEventTimes(0);
+  });
+
+  it('should trigger bqBreadcrumbClick on Enter', async () => {
+    const page = await newE2EPage();
+    await page.setContent(`
+      <bq-breadcrumb>
+        <bq-breadcrumb-item>Home</bq-breadcrumb-item>
+      </bq-breadcrumb>
+    `);
+
+    const bqBlur = await page.spyOnEvent('bqBreadcrumbBlur');
+    const bqFocus = await page.spyOnEvent('bqBreadcrumbFocus');
+    const bqClick = await page.spyOnEvent('bqBreadcrumbClick');
+
+    await page.keyboard.press('Tab');
+    await page.keyboard.press('Enter');
+
+    expect(bqFocus).toHaveReceivedEventTimes(1);
+    expect(bqClick).toHaveReceivedEventTimes(1);
+    expect(bqBlur).toHaveReceivedEventTimes(0);
+  });
+
+  it('should render custom separator ', async () => {
+    const page = await newE2EPage();
+    await page.setContent(
+      `<bq-breadcrumb>
+        <bq-icon name="caret-right" slot="separator" size="12"></bq-icon>
+
+        <bq-breadcrumb-item>
+          <bq-icon name="house-line" size="16"></bq-icon>
+          <span>Home</span>
+        </bq-breadcrumb-item>
+        <bq-breadcrumb-item>Application Center</bq-breadcrumb-item>
+      </bq-breadcrumb>
+    `,
+    );
+
+    const separator = await page.find('bq-breadcrumb >>> bq-icon[slot="separator"]');
+
+    expect(separator).toBeDefined();
+  });
+});
diff --git a/packages/bee-q/src/components/breadcrumb/_storybook/bq-breadcrumb.mdx b/packages/bee-q/src/components/breadcrumb/_storybook/bq-breadcrumb.mdx
new file mode 100644
index 000000000..4e0827798
--- /dev/null
+++ b/packages/bee-q/src/components/breadcrumb/_storybook/bq-breadcrumb.mdx
@@ -0,0 +1,39 @@
+import { ArgTypes, Stories, Title, Subtitle } from '@storybook/addon-docs';
+
+<Title>Breadcrumb</Title>
+
+The Breadcrumb Component helps users understand their current location within a website or application's hierarchical structure.
+It is a list of links or buttons that provides context and helps users understand where they are within the overall information architecture and provides a sense of orientation and control.
+Each item in the Breadcrumb Component represents a level in the hierarchy of the application.
+
+<Subtitle>Usage</Subtitle>
+
+- Provide context: Breadcrumbs give users an overview of the page hierarchy they're currently in, providing them with a sense of context and helping them understand where they are in relation to the rest of the site.
+- Improve navigation: Breadcrumbs make it easier for users to move up and down the page hierarchy, quickly returning to previously visited pages or exploring new sections of the site.
+- Enhance discoverability: By highlighting the path to the current page, breadcrumbs can also help users discover new content and features within the site.
+
+<Subtitle>👍 When to use</Subtitle>
+
+Do's:
+
+- Use clear and concise labels for each breadcrumb, describing the content of the page or section it represents.
+- Make sure the breadcrumb labels accurately reflect the page hierarchy, with the most general sections at the beginning and the most specific sections at the end.
+- Keep breadcrumbs visible and accessible, either by placing them at the top of the page or by having them fixed to the top of the screen as the user scrolls.
+- Make breadcrumbs clickable, allowing users to easily navigate back to previously visited pages.
+
+Don'ts:
+
+- Overuse breadcrumbs, or use them in situations where they don't provide any meaningful context or benefit to the user.
+- Use breadcrumbs as a substitute for proper navigation, as they should complement, not replace, other navigation elements such as menus and links.
+- Make breadcrumbs too small or hard to read, as this can make it difficult for users to understand the context and navigate the site effectively.
+- Use breadcrumbs as a way to display too much information, as this can make the navigation overwhelming and confusing for users.
+
+<Title>Properties</Title>
+
+<Subtitle>`<bq-readcrumb>`</Subtitle>
+
+<ArgTypes of="bq-breadcrumb" />
+
+<Subtitle>`<bq-readcrumb-item>`</Subtitle>
+
+<ArgTypes of="bq-breadcrumb-item" />
diff --git a/packages/bee-q/src/components/breadcrumb/_storybook/bq-breadcrumb.stories.tsx b/packages/bee-q/src/components/breadcrumb/_storybook/bq-breadcrumb.stories.tsx
new file mode 100644
index 000000000..11023a37c
--- /dev/null
+++ b/packages/bee-q/src/components/breadcrumb/_storybook/bq-breadcrumb.stories.tsx
@@ -0,0 +1,95 @@
+import type { Args, Meta, StoryObj } from '@storybook/web-components';
+
+import { ifDefined } from 'lit/directives/if-defined.js';
+
+import { html } from 'lit-html';
+
+import mdx from './bq-breadcrumb.mdx';
+
+const meta: Meta = {
+  title: 'Components/Breadcrumb',
+  component: 'bq-breadcrumb',
+  parameters: {
+    docs: {
+      page: mdx,
+    },
+  },
+  argTypes: {
+    'aria-label': { control: 'text' },
+    // Event handlers
+    bqBreadcrumbBlur: { action: 'bqBlur' },
+    bqBreadcrumbClick: { action: 'bqClick' },
+    bqBreadcrumbFocus: { action: 'bqFocus' },
+    // Not part of the public API, so we don't want to expose it in the docs
+    text: { control: 'text', table: { disable: true } },
+    htmlNode: { control: 'object', table: { disable: true } },
+    useLinks: { control: 'boolean', table: { disable: true } },
+  },
+  args: {
+    'aria-label': 'Breadcrumbs',
+    text: 'text',
+    htmlNode: '',
+    useLinks: false,
+  },
+};
+export default meta;
+
+type Story = StoryObj;
+
+const Template = (args: Args) => html`
+  <bq-breadcrumb
+    @bqBreadcrumbBlur=${args.bqBreadcrumbBlur}
+    @bqBreadcrumbClick=${args.bqBreadcrumbClick}
+    @bqBreadcrumbFocus=${args.bqBreadcrumbFocus}
+  >
+    ${args.htmlNode}
+    <bq-breadcrumb-item
+      href=${ifDefined(args.useLinks ? 'https://example.com/' : null)}
+      target=${ifDefined(args.useLinks ? '_blank' : null)}
+      aria-label="Home page"
+    >
+      <bq-icon name="house-line" size="16"></bq-icon>
+    </bq-breadcrumb-item>
+    <bq-breadcrumb-item
+      href=${ifDefined(args.useLinks ? 'https://example.com/' : null)}
+      target=${ifDefined(args.useLinks ? '_blank' : null)}
+      aria-label="Men clothing"
+    >
+      Men's Clothing
+    </bq-breadcrumb-item>
+    <bq-breadcrumb-item
+      href=${ifDefined(args.useLinks ? 'https://example.com/' : null)}
+      target=${ifDefined(args.useLinks ? '_blank' : null)}
+      aria-label="Shirts"
+    >
+      <bq-icon name="shirt-folded" size="16"></bq-icon>
+      Shirts
+    </bq-breadcrumb-item>
+    <bq-breadcrumb-item
+      href=${ifDefined(args.useLinks ? 'https://example.com/' : null)}
+      target=${ifDefined(args.useLinks ? '_blank' : null)}
+      aria-label="Casual shirts"
+    >
+      Casual shirts
+    </bq-breadcrumb-item>
+  </bq-breadcrumb>
+`;
+
+export const Default: Story = {
+  render: Template,
+  args: {},
+};
+
+export const CaretSeparator: Story = {
+  render: Template,
+  args: {
+    htmlNode: Object.assign(document.createElement('bq-icon'), { name: 'caret-right', size: '12', slot: 'separator' }),
+  },
+};
+
+export const Links: Story = {
+  render: Template,
+  args: {
+    useLinks: true,
+  },
+};
diff --git a/packages/bee-q/src/components/breadcrumb/bq-breadcrumb.tsx b/packages/bee-q/src/components/breadcrumb/bq-breadcrumb.tsx
new file mode 100644
index 000000000..bd8e43a73
--- /dev/null
+++ b/packages/bee-q/src/components/breadcrumb/bq-breadcrumb.tsx
@@ -0,0 +1,131 @@
+import { h, Component, Element, Listen, Event, EventEmitter, Host, Prop } from '@stencil/core';
+
+import { isHTMLElement } from '../../shared/utils';
+
+/**
+ * @part navigation - The `nav` tag that loads the breadcrumb items
+ */
+@Component({
+  tag: 'bq-breadcrumb',
+  styleUrl: './scss/bq-breadcrumb.scss',
+  shadow: true,
+})
+export class BqBreadcrumb {
+  // Own Properties
+  // ====================
+
+  private spanElem: HTMLElement;
+
+  // Reference to host HTML element
+  // ===================================
+
+  @Element() el!: HTMLBqBreadcrumbElement;
+
+  // State() variables
+  // Inlined decorator, alphabetical order
+  // =======================================
+
+  // Public Property API
+  // ========================
+
+  /** The `aria-label` attribute to describe the type of navigation */
+  @Prop({ reflect: true }) ariaLabel: string = 'Breadcrumbs';
+
+  // Prop lifecycle events
+  // =======================
+
+  // Events section
+  // Requires JSDocs for public API documentation
+  // ==============================================
+
+  /** Handler to be called when `bq-breadcrumb-item` item loses focus. */
+  @Event() bqBreadcrumbBlur: EventEmitter<HTMLBqBreadcrumbItemElement>;
+
+  /** Handler to be called when `bq-breadcrumb-item` item gets focus. */
+  @Event() bqBreadcrumbFocus: EventEmitter<HTMLBqBreadcrumbItemElement>;
+
+  /** Handler to be called when `bq-breadcrumb-item` is selected (on click/enter press). */
+  @Event() bqBreadcrumbClick: EventEmitter<HTMLBqBreadcrumbItemElement>;
+
+  // Component lifecycle events
+  // Ordered by their natural call order
+  // =====================================
+
+  // Listeners
+  // ==============
+
+  @Listen('bqBlur', { passive: true })
+  onBlur(event: CustomEvent<HTMLElement>) {
+    if (isHTMLElement(event.detail, 'bq-breadcrumb-item')) this.bqBreadcrumbBlur.emit(event.detail);
+  }
+
+  @Listen('bqFocus', { passive: true })
+  onFocus(event: CustomEvent<HTMLElement>) {
+    if (isHTMLElement(event.detail, 'bq-breadcrumb-item')) this.bqBreadcrumbFocus.emit(event.detail);
+  }
+
+  @Listen('bqClick', { passive: true })
+  onClick(event: CustomEvent<HTMLElement>) {
+    if (isHTMLElement(event.detail, 'bq-breadcrumb-item')) this.bqBreadcrumbClick.emit(event.detail);
+  }
+
+  // Public methods API
+  // These methods are exposed on the host element.
+  // Always use two lines.
+  // Public Methods must be async.
+  // Requires JSDocs for public API documentation.
+  // ===============================================
+
+  // Local methods
+  // Internal business logic.
+  // These methods cannot be called from the host element.
+  // =======================================================
+
+  private setSeparator = (): void => {
+    this.breadcrumbItems.forEach((item, index, arr) => {
+      item.isLastItem = index === arr.length - 1;
+      !item.isLastItem && item.append(this.getSeparatorElem());
+    });
+  };
+
+  /**
+   * clone original element and add slot attr
+   * @returns cloned separator element
+   */
+  private getSeparatorElem = (): HTMLElement => {
+    const clone = this.separatorFromSlot.cloneNode(true) as HTMLElement;
+    clone.slot = 'separator';
+
+    return clone;
+  };
+
+  private get breadcrumbItems(): HTMLBqBreadcrumbItemElement[] {
+    return Array.from(this.el.querySelectorAll('bq-breadcrumb-item'));
+  }
+
+  private get separatorFromSlot() {
+    return this.spanElem
+      .querySelector<HTMLSlotElement>('slot[name="separator"]')
+      .assignedElements({ flatten: true })[0] as HTMLElement;
+  }
+
+  // render() function
+  // Always the last one in the class.
+  // ===================================
+
+  render() {
+    return (
+      <Host>
+        <nav class="flex items-center" aria-label={this.ariaLabel} part="navigation">
+          <slot onSlotchange={this.setSeparator}></slot>
+        </nav>
+
+        <span hidden aria-hidden="true" ref={(element) => (this.spanElem = element)}>
+          <slot name="separator">
+            <span class="flex w-3 items-center justify-center">/</span>
+          </slot>
+        </span>
+      </Host>
+    );
+  }
+}
diff --git a/packages/bee-q/src/components/breadcrumb/readme.md b/packages/bee-q/src/components/breadcrumb/readme.md
new file mode 100644
index 000000000..41cc64e88
--- /dev/null
+++ b/packages/bee-q/src/components/breadcrumb/readme.md
@@ -0,0 +1,33 @@
+# bq-breadcrumb
+
+
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property    | Attribute    | Description                                                   | Type     | Default         |
+| ----------- | ------------ | ------------------------------------------------------------- | -------- | --------------- |
+| `ariaLabel` | `aria-label` | The `aria-label` attribute to describe the type of navigation | `string` | `'Breadcrumbs'` |
+
+
+## Events
+
+| Event               | Description                                                                        | Type                                       |
+| ------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------ |
+| `bqBreadcrumbBlur`  | Handler to be called when `bq-breadcrumb-item` item loses focus.                   | `CustomEvent<HTMLBqBreadcrumbItemElement>` |
+| `bqBreadcrumbClick` | Handler to be called when `bq-breadcrumb-item` is selected (on click/enter press). | `CustomEvent<HTMLBqBreadcrumbItemElement>` |
+| `bqBreadcrumbFocus` | Handler to be called when `bq-breadcrumb-item` item gets focus.                    | `CustomEvent<HTMLBqBreadcrumbItemElement>` |
+
+
+## Shadow Parts
+
+| Part           | Description                                   |
+| -------------- | --------------------------------------------- |
+| `"navigation"` | The `nav` tag that loads the breadcrumb items |
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*
diff --git a/packages/bee-q/src/components/breadcrumb/scss/bq-breadcrumb.scss b/packages/bee-q/src/components/breadcrumb/scss/bq-breadcrumb.scss
new file mode 100644
index 000000000..c90c4a468
--- /dev/null
+++ b/packages/bee-q/src/components/breadcrumb/scss/bq-breadcrumb.scss
@@ -0,0 +1,7 @@
+/* -------------------------------------------------------------------------- */
+/*                                Breadcrumb styles                */
+/* -------------------------------------------------------------------------- */
+
+:host {
+  @apply block;
+}