Merge pull request adevinta#2362 from adevinta/init-breadcrumb-component

feat(breadcrumb): new breadcrumb component

packages/components/breadcrumb/.npmignore

@@ -0,0 +1,2 @@
+src
+**/*.stories.*

packages/components/breadcrumb/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Adevinta ASA.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/components/breadcrumb/README.md

@@ -0,0 +1,13 @@
+# Breadcrumb
+> @spark-ui/breadcrumb
+
+[![storybook](https://img.shields.io/badge/storybook-black?logo=storybook)](https://sparkui.vercel.app/?path=/docs/components-breadcrumb--docs)
+[![documentation](https://img.shields.io/badge/documentation-black?logo=googledocs)](https://sparkui-adv.vercel.app/docs/components/breadcrumb)
+[![issue](https://img.shields.io/badge/report%20a%20bug-black?logo=openbugbounty&logoColor=red)](https://github.com/adevinta/spark/issues/new?&projects=4&template=bug-report.yml&assignees=&labels=Component,Component%3A%20breadcrumb)
+[![npm](https://img.shields.io/npm/dt/%40spark-ui/breadcrumb?logo=npm&labelColor=black)](https://www.npmjs.com/package/@spark-ui/breadcrumb)
+
+
+This package is part of the [`@spark-ui`](https://github.com/adevinta/spark) react-js user interface component library project.
+
+[![Issues open](https://img.shields.io/github/issues-search/adevinta/spark?query=is%3Aopen%20label%3A%22Component%3A%20breadcrumb%22&logo=openbugbounty&logoColor=red&label=issues%20open&color=red)](https://github.com/adevinta/spark/issues?q=is%3Aopen+label%3AComponent%3A%20breadcrumb)
+[![NPM](https://img.shields.io/npm/l/%40spark-ui%2Fbreadcrumb)](https://github.com/adevinta/spark/blob/main/packages/components/breadcrumb/LICENSE.md)

packages/components/breadcrumb/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@spark-ui/breadcrumb",
+  "version": "0.0.0",
+  "description": "navigation pattern that helps users understand the hierarchy of a website",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "@spark-ui",
+    "react",
+    "component",
+    "accessible",
+    "accessibility",
+    "wai-aria",
+    "aria",
+    "a11y",
+    "breadcrumb"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "vite build"
+  },
+  "peerDependencies": {
+    "@spark-ui/tailwind-plugins": "latest",
+    "@spark-ui/theme-utils": "latest",
+    "react": "^18.0 || ^19.0",
+    "react-dom": "^18.0 || ^19.0",
+    "tailwindcss": "^3.0.0"
+  },
+  "dependencies": {
+    "@spark-ui/slot": "^5.0.27",
+    "@spark-ui/text-link": "^5.0.27",
+    "@spark-ui/icon": "^5.0.27",
+    "@spark-ui/icons": "^5.0.27",
+    "class-variance-authority": "0.7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adevinta/spark.git",
+    "directory": "packages/components/breadcrumb"
+  },
+  "config": {
+    "title": "breadcrumb",
+    "category": "components"
+  },
+  "bugs": {
+    "url": "https://github.com/adevinta/spark/issues?q=is%3Aopen+label%3A%22Component%3A+breadcrumb%22"
+  },
+  "homepage": "https://sparkui.vercel.app",
+  "license": "MIT"
+}

packages/components/breadcrumb/src/Breadcrumb.doc.mdx

@@ -0,0 +1,85 @@
+import { Meta, Canvas } from '@storybook/addon-docs'
+import { ArgTypes } from '@docs/helpers/ArgTypes'
+import { Kbd } from '@spark-ui/kbd'
+
+import { Breadcrumb } from '.'
+
+import * as stories from './Breadcrumb.stories'
+
+<Meta of={stories} />
+
+# Breadcrumb
+
+Navigation pattern that helps users understand the hierarchy of a website
+
+## Install
+
+```sh
+npm install @spark-ui/breadcrumb
+```
+
+## Import
+
+```tsx
+import { Breadcrumb } from '@spark-ui/breadcrumb'
+```
+
+## Props
+
+<ArgTypes
+  of={Breadcrumb}
+  description="Contains all the parts of a breakpoint. Navigation area."
+  subcomponents={{
+    'Breadcrumb.Item': {
+      of: Breadcrumb.Item,
+      description: 'List item to use inside of `Breadcrumb` directly.',
+    },
+    'Breadcrumb.Link': {
+      of: Breadcrumb.Link,
+      description: 'Use inside `Breadcrumb.Item` if your item must be a link.',
+    },
+    'Breadcrumb.CurrentPage': {
+      of: Breadcrumb.CurrentPage,
+      description:
+        'Use inside `Breadcrumb.Item` if your item is the current page (non-interactive link).',
+    },
+    'Breadcrumb.Separator': {
+      of: Breadcrumb.Separator,
+      description: 'Separator to use between each `Breadcrumb.Item`. Content can be customized.',
+    },
+  }}
+/>
+
+## Usage
+
+### Default
+
+<Canvas of={stories.Default} />
+
+### Custom Separator
+
+Use the `children` property of `Breadcrumb.Separator` to use a different icon for the separator. You can also use raw text.
+
+<Canvas of={stories.CustomSeparator} />
+
+### Truncate
+
+Apply a maximum width on an element to truncate it automatically.
+
+<Canvas of={stories.Truncate} />
+
+## Accessibility
+
+Adheres to the [Breadcrumb WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/).
+
+### Keyboard Interaction
+
+- <Kbd>Tab</Kbd>: Focuses the next item.
+- <Kbd>Shift</Kbd> + <Kbd>Tab</Kbd>: Focuses the previous item.
+- <Kbd>Enter</Kbd>: Triggers an item link.
+
+### WAI-ARIA Roles, States, and Properties
+
+- Breadcrumb trail is contained within a navigation landmark region.
+- The landmark region is labelled via [aria-label](https://w3c.github.io/aria/#aria-label) or [aria-labelledby](https://w3c.github.io/aria/#aria-labelledby).
+- The link to the current page has [aria-current](https://w3c.github.io/aria/#aria-current) set to `page`. If the element representing the current page is not a link, aria-current is optional.

packages/components/breadcrumb/src/Breadcrumb.stories.tsx

@@ -0,0 +1,86 @@
+import { Icon } from '@spark-ui/icon'
+import { ArrowRight } from '@spark-ui/icons/dist/icons/ArrowRight'
+import { Meta, StoryFn } from '@storybook/react'
+
+import { Breadcrumb } from '.'
+
+const meta: Meta<typeof Breadcrumb> = {
+  title: 'Components/Breadcrumb',
+  component: Breadcrumb,
+}
+
+export default meta
+
+export const Default: StoryFn = _args => (
+  <Breadcrumb aria-label="Breadcrumb">
+    <Breadcrumb.Item>
+      <Breadcrumb.Link href="/">Home</Breadcrumb.Link>
+    </Breadcrumb.Item>
+
+    <Breadcrumb.Separator />
+
+    <Breadcrumb.Item>
+      <Breadcrumb.Link href="/?path=/docs/experimental-breadcrumb--docs">
+        Components
+      </Breadcrumb.Link>
+    </Breadcrumb.Item>
+
+    <Breadcrumb.Separator />
+
+    <Breadcrumb.Item>
+      <Breadcrumb.CurrentPage>Breadcrumb</Breadcrumb.CurrentPage>
+    </Breadcrumb.Item>
+  </Breadcrumb>
+)
+
+export const CustomSeparator: StoryFn = _args => (
+  <Breadcrumb aria-label="Breadcrumb">
+    <Breadcrumb.Item>
+      <Breadcrumb.Link href="/">Home</Breadcrumb.Link>
+    </Breadcrumb.Item>
+
+    <Breadcrumb.Separator>
+      <Icon>
+        <ArrowRight />
+      </Icon>
+    </Breadcrumb.Separator>
+
+    <Breadcrumb.Item>
+      <Breadcrumb.Link href="/?path=/docs/experimental-breadcrumb--docs">
+        Components
+      </Breadcrumb.Link>
+    </Breadcrumb.Item>
+
+    <Breadcrumb.Separator>
+      <Icon>
+        <ArrowRight />
+      </Icon>
+    </Breadcrumb.Separator>
+
+    <Breadcrumb.Item>
+      <Breadcrumb.CurrentPage>Breadcrumb</Breadcrumb.CurrentPage>
+    </Breadcrumb.Item>
+  </Breadcrumb>
+)
+
+export const Truncate: StoryFn = _args => (
+  <Breadcrumb aria-label="Breadcrumb">
+    <Breadcrumb.Item>
+      <Breadcrumb.Link href="/">Home</Breadcrumb.Link>
+    </Breadcrumb.Item>
+
+    <Breadcrumb.Separator />
+
+    <Breadcrumb.Item>
+      <Breadcrumb.Link href="/?path=/docs/experimental-breadcrumb--docs" className="max-w-[100px]">
+        Components list - Feel free to use them
+      </Breadcrumb.Link>
+    </Breadcrumb.Item>
+
+    <Breadcrumb.Separator />
+
+    <Breadcrumb.Item>
+      <Breadcrumb.CurrentPage>Breadcrumb</Breadcrumb.CurrentPage>
+    </Breadcrumb.Item>
+  </Breadcrumb>
+)

packages/components/breadcrumb/src/Breadcrumb.test.tsx

@@ -0,0 +1,71 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+
+import { Breadcrumb } from '.'
+
+describe('Breadcrumb', () => {
+  it('should render all parts', () => {
+    // Given a breadcrumb with links, separator and current page item.
+    render(
+      <Breadcrumb aria-label="Breadcrumb">
+        <Breadcrumb.Item>
+          <Breadcrumb.Link href="/">Home</Breadcrumb.Link>
+        </Breadcrumb.Item>
+
+        <Breadcrumb.Separator />
+
+        <Breadcrumb.Item>
+          <Breadcrumb.Link href="/docs/components">Components</Breadcrumb.Link>
+        </Breadcrumb.Item>
+
+        <Breadcrumb.Separator />
+
+        <Breadcrumb.Item>
+          <Breadcrumb.CurrentPage>Breadcrumb</Breadcrumb.CurrentPage>
+        </Breadcrumb.Item>
+      </Breadcrumb>
+    )
+
+    expect(screen.getByRole('navigation', { name: 'Breadcrumb' })).toBeInTheDocument()
+
+    // Then Breadcrumb links should be rendered
+    expect(screen.getByRole('link', { name: 'Home' })).toHaveAttribute('href', '/')
+    expect(screen.getByRole('link', { name: 'Components' })).toHaveAttribute(
+      'href',
+      '/docs/components'
+    )
+
+    // Then breadcrumb current page should be rendered
+    const currentPageLink = screen.getByRole('link', { name: 'Breadcrumb' })
+    expect(currentPageLink).toHaveAttribute('aria-current', 'page')
+
+    // Then separators should be rendered (hidden)
+    expect(screen.getAllByRole('presentation', { hidden: true })).toHaveLength(2)
+  })
+
+  it('should render custom separators', () => {
+    // Given a breadcrumb with links, separator and current page item.
+    render(
+      <Breadcrumb aria-label="Breadcrumb">
+        <Breadcrumb.Item>
+          <Breadcrumb.Link href="/">Home</Breadcrumb.Link>
+        </Breadcrumb.Item>
+
+        <Breadcrumb.Separator>__</Breadcrumb.Separator>
+
+        <Breadcrumb.Item>
+          <Breadcrumb.Link href="/docs/components">Components</Breadcrumb.Link>
+        </Breadcrumb.Item>
+
+        <Breadcrumb.Separator>__</Breadcrumb.Separator>
+
+        <Breadcrumb.Item>
+          <Breadcrumb.CurrentPage>Breadcrumb</Breadcrumb.CurrentPage>
+        </Breadcrumb.Item>
+      </Breadcrumb>
+    )
+
+    // Then separators should be rendered with their custom content
+    expect(screen.getAllByText('__')).toHaveLength(2)
+  })
+})