import type { Meta, StoryObj } from '@storybook/web-components-vite'; import { html } from 'lit'; import './index.ts'; import type { USABreadcrumb, BreadcrumbItem } from './usa-breadcrumb.js'; const meta: Meta = { title: 'Navigation/Breadcrumb', component: 'usa-breadcrumb', parameters: { layout: 'padded', docs: { description: { component: ` The USWDS Breadcrumb component provides users with navigational context by showing their current location within a website's hierarchy. It helps users understand where they are and provides links to navigate back to parent pages. This web component implementation maintains full USWDS compliance while providing a modern custom element API. It supports automatic current page detection, custom styling options, and comprehensive accessibility features. Breadcrumbs are essential for user experience on websites with deep information hierarchies, helping users find information efficiently. `, }, }, }, argTypes: { items: { control: 'object', description: 'Array of breadcrumb items with labels, links, and current state', }, wrap: { control: 'boolean', description: 'Allow breadcrumb items to wrap to multiple lines', }, }, }; export default meta; type Story = StoryObj; // Sample breadcrumb data for stories const basicBreadcrumbs: BreadcrumbItem[] = [ { label: 'Home', href: '/' }, { label: 'Products', href: '/products' }, { label: 'Category', href: '/products/category' }, { label: 'Current Page', current: true }, ]; const shortBreadcrumbs: BreadcrumbItem[] = [ { label: 'Home', href: '/' }, { label: 'Current Page', current: true }, ]; const longBreadcrumbs: BreadcrumbItem[] = [ { label: 'Home', href: '/' }, { label: 'Company', href: '/company' }, { label: 'Technology', href: '/company/technology' }, { label: 'Development', href: '/company/technology/development' }, { label: 'Web Services', href: '/company/technology/development/web' }, { label: 'Frontend Team', href: '/company/technology/development/web/frontend' }, { label: 'Design System', href: '/company/technology/development/web/frontend/design' }, { label: 'Current Documentation', current: true }, ]; export const Default: Story = { args: { items: basicBreadcrumbs, wrap: false, }, }; export const ShortPath: Story = { args: { items: shortBreadcrumbs, wrap: false, }, }; export const LongPath: Story = { args: { items: longBreadcrumbs, wrap: false, }, }; export const WithWrap: Story = { args: { items: longBreadcrumbs, wrap: true, }, render: (args) => html`

📱 Responsive Wrapping Behavior:

  • Viewport ≥480px: Breadcrumb items wrap to multiple lines inside the constrained container
  • Viewport <480px: Shows mobile condensed view with back arrow (USWDS standard)

Resize browser window to test both modes!

`, }; export const SingleItem: Story = { args: { items: [{ label: 'Home Page', href: '/' }], wrap: false, }, }; export const WithoutCurrentFlag: Story = { args: { items: [ { label: 'Home', href: '/' }, { label: 'Section', href: '/section' }, { label: 'Last Item' }, // No current flag, but treated as current ], wrap: false, }, }; export const ResponsiveDemo: Story = { args: { items: longBreadcrumbs, wrap: true, }, parameters: { viewport: { defaultViewport: 'tablet', }, layout: 'padded', }, render: (args) => html`

⚠️ Important - Viewport Requirements:

  • Desktop (480px+): Wrapping works - items flow to multiple lines
  • Mobile (<480px): USWDS shows condensed view with back arrow regardless of wrap setting
  • Current viewport:

Resize your browser window above 480px to see the wrapping behavior in action.

`, }; export const InteractiveDemo: Story = { args: { items: basicBreadcrumbs, wrap: false, }, render: (args) => html` { console.log('Breadcrumb clicked:', e.detail); alert(`Navigating to: ${e.detail.label} (${e.detail.href})`); e.preventDefault(); // Prevent navigation in Storybook }} >

Breadcrumb Navigation Testing Guide

Interactive Features:

  • Click any non-current breadcrumb item to see navigation event
  • Current page item is not clickable (properly styled)
  • Keyboard navigation works with Tab and Enter keys
  • Screen readers announce navigation context

Accessibility Testing:

  • Use keyboard navigation (Tab through items)
  • Test with screen readers (proper navigation landmark)
  • Verify aria-current="page" on current item
  • Check semantic HTML structure (nav > ol > li)

Website Usage:

  • Essential for deep information hierarchies
  • Helps users navigate complex site structures
  • Provides clear context for current page location
  • Improves SEO and discoverability
`, }; export const AccessibilityDemo: Story = { args: { items: basicBreadcrumbs, wrap: false, }, render: (args) => html`

Accessibility Features

  • Semantic Structure: Uses proper HTML5 nav and ordered list
  • ARIA Labels: Navigation landmark with descriptive label
  • Current Page: Properly marked with aria-current="page"
  • Keyboard Navigation: All links accessible via keyboard
  • Screen Reader Support: Clear navigation context

✅ WCAG AA Compliance

  • Color contrast meets requirements
  • Keyboard navigation fully functional
  • Screen reader announces navigation context
  • Focus indicators are visible and clear
  • Semantic HTML structure for assistive technology
`, }; export const ComparisonDemo: Story = { parameters: { controls: { disable: true }, // Static demo - no interactive controls needed }, render: () => html`

Standard Breadcrumb

Long Breadcrumb (No Wrap) - Constrained Width

Notice: Ellipsis truncation at 480px+

Long Breadcrumb (With Wrap) - Constrained Width

Notice: Items wrap to multiple lines at 480px+

Single Item

🔍 Responsive Behavior (USWDS Standard):

  • Mobile (<480px): Shows condensed view with back arrow - wrap setting ignored
  • Desktop (≥480px):
    • No Wrap: Single line with ellipsis truncation
    • With Wrap: Multiple lines, items flow naturally

💡 Tip: Resize your browser to see the responsive behavior in action!

When to Use Different Patterns:

  • Standard: Most common pattern for 2-4 level hierarchies
  • Long (No Wrap): Desktop layouts with ample horizontal space
  • Long (With Wrap): Narrow containers or when you want full breadcrumb visibility
  • Single Item: Top-level pages or simple site structures
`, }; export const CustomStylingExample: Story = { args: { items: basicBreadcrumbs, wrap: false, }, render: (args) => html`

Custom Styling Example

This example demonstrates custom styling while maintaining USWDS accessibility:

  • Enhanced background and border styling
  • Custom link colors with hover effects
  • Emphasized current page styling
  • Maintained focus indicators and accessibility

Note: Always ensure custom styles maintain accessibility and usability standards.

`, }; export const EmptyState: Story = { args: { items: [], wrap: false, }, render: (args) => html`

Empty Breadcrumb

This shows how the component handles an empty items array. The navigation structure is still present but contains no items.

`, };