feat(breadcrumb): new breadcrumb component boilerplate

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,46 @@
+{
+  "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"
+  },
+  "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,54 @@
+import { Meta, Canvas } from '@storybook/addon-docs'
+import { ArgTypes } from '@docs/helpers/ArgTypes'
+
+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.',
+    },
+  }}
+/>
+
+## Variants
+
+<Canvas of={stories.Default} />

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

@@ -0,0 +1,30 @@
+import { Meta, StoryFn } from '@storybook/react'
+
+import { Breadcrumb } from '.'
+
+const meta: Meta<typeof Breadcrumb> = {
+  title: 'Experimental/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="/docs/components">Components</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,70 @@
+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.Page>Breadcrumb</Breadcrumb.Page>
+        </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
+    expect(screen.getByRole('link', { name: 'Breadcrumb' })).not.toHaveAttribute('href')
+
+    // 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.Page>Breadcrumb</Breadcrumb.Page>
+        </Breadcrumb.Item>
+      </Breadcrumb>
+    )
+
+    // Then separators should be rendered with their custom content
+    expect(screen.getAllByText('__')).toHaveLength(2)
+  })
+})

packages/components/breadcrumb/src/Breadcrumb.tsx

@@ -0,0 +1,22 @@
+import { cx } from 'class-variance-authority'
+import { ComponentPropsWithoutRef, forwardRef } from 'react'
+
+export interface BreadcrumbProps extends ComponentPropsWithoutRef<'nav'> {
+  className?: string
+  ['aria-label']: string
+}
+
+export const Breadcrumb = forwardRef<HTMLOListElement, BreadcrumbProps>(
+  ({ className, 'aria-label': ariaLabel, ...rest }, ref) => {
+    return (
+      <nav data-spark-component="breadcrumb" ref={ref} aria-label={ariaLabel} className={className}>
+        <ol
+          className={cx('flex flex-wrap items-center gap-sm break-words text-caption')}
+          {...rest}
+        />
+      </nav>
+    )
+  }
+)
+
+Breadcrumb.displayName = 'Breadcrumb.Breadcrumb'

packages/components/breadcrumb/src/BreadcrumbCurrentPage.tsx

@@ -0,0 +1,27 @@
+import { Slot } from '@spark-ui/slot'
+import { ComponentPropsWithoutRef, forwardRef } from 'react'
+
+export interface CurrentPageProps extends ComponentPropsWithoutRef<'span'> {
+  asChild?: boolean
+  className?: string
+}
+
+export const CurrentPage = forwardRef<HTMLSpanElement, CurrentPageProps>(
+  ({ asChild = false, className, ...rest }, ref) => {
+    const Component = asChild ? Slot : 'span'
+
+    return (
+      <Component
+        data-spark-component="breadcrumb-current-page"
+        role="link"
+        aria-current="page"
+        aria-disabled
+        className={className}
+        ref={ref}
+        {...rest}
+      />
+    )
+  }
+)
+
+CurrentPage.displayName = 'Breadcrumb.CurrentPage'

packages/components/breadcrumb/src/BreadcrumbItem.tsx

@@ -0,0 +1,19 @@
+import { cx } from 'class-variance-authority'
+import { ComponentPropsWithoutRef, forwardRef } from 'react'
+
+export interface ItemProps extends ComponentPropsWithoutRef<'li'> {
+  className?: string
+}
+
+export const Item = forwardRef<HTMLLIElement, ItemProps>(({ className, ...rest }, ref) => {
+  return (
+    <li
+      data-spark-component="breadcrumb-item"
+      ref={ref}
+      className={cx('inline-flex items-center gap-sm', className)}
+      {...rest}
+    />
+  )
+})
+
+Item.displayName = 'Breadcrumb.Item'

packages/components/breadcrumb/src/BreadcrumbLink.tsx

@@ -0,0 +1,26 @@
+import { Slot } from '@spark-ui/slot'
+import { ComponentPropsWithoutRef, forwardRef } from 'react'
+
+export interface LinkProps extends ComponentPropsWithoutRef<'a'> {
+  asChild?: boolean
+  className?: string
+  href?: string
+}
+
+export const Link = forwardRef<HTMLAnchorElement, LinkProps>(
+  ({ asChild = false, className, href, ...rest }, ref) => {
+    const Component = asChild ? Slot : 'a'
+
+    return (
+      <Component
+        data-spark-component="breadcrumb-link"
+        href={href}
+        ref={ref}
+        className={className}
+        {...rest}
+      />
+    )
+  }
+)
+
+Link.displayName = 'Breadcrumb.Link'