import type { Meta, StoryObj } from '@storybook/web-components-vite'; import { html } from 'lit'; import './index.ts'; import '../icon/index.ts'; import type { USALink } from './usa-link.js'; const meta: Meta = { title: 'Actions/Link', component: 'usa-link', parameters: { layout: 'padded', docs: { description: { component: ` # USA Link The USA Link component provides consistent link styling and behavior using official USWDS standards. It automatically handles external link security, accessibility attributes, and proper visual styling for web applications. ## Features - Automatic external link detection with security attributes - Multiple variants (default, external, alt, unstyled) - Built-in accessibility support with ARIA labels - Consistent USWDS styling and visual indicators - Download link support - Custom event handling for analytics and tracking ## Usage Guidelines - Use for navigation within and outside your application - External links automatically get security attributes (noopener, noreferrer) - Provide descriptive link text that makes sense out of context - Use aria-label for additional context when needed - Consider download attribute for file links ## Accessibility - Links are keyboard accessible by default - External links include proper security attributes - ARIA labels supported for additional context - Focus indicators meet WCAG contrast requirements - Link text should be descriptive and meaningful `, }, }, }, argTypes: { href: { control: 'text', description: 'URL destination for the link', }, target: { control: { type: 'select' }, options: ['', '_blank', '_self', '_parent', '_top'], description: 'How to open the link (auto-set for external links)', }, rel: { control: 'text', description: 'Relationship attributes (auto-enhanced for external links)', }, variant: { control: { type: 'select' }, options: ['default', 'external', 'alt', 'unstyled'], description: 'Visual variant of the link', }, external: { control: 'boolean', description: 'Force external link styling and behavior', }, unstyled: { control: 'boolean', description: 'Remove USWDS styling', }, ariaLabel: { control: 'text', description: 'Accessible label for screen readers', }, download: { control: 'text', description: 'Filename for download links', }, }, }; export default meta; type Story = StoryObj; export const Default: Story = { args: { href: '/about', variant: 'default', }, render: (args) => html` About Our Company `, }; export const ExternalLink: Story = { args: { href: 'https://www.usa.gov', variant: 'external', }, render: (args) => html` Visit USA.gov `, }; export const AlternativeVariant: Story = { args: { href: '/services', variant: 'alt', }, render: (args) => html` Our Services `, }; export const UnstyledLink: Story = { args: { href: '/contact', variant: 'unstyled', }, render: (args) => html` Contact Us (Unstyled) `, }; export const DownloadLink: Story = { args: { href: '/documents/annual-report.pdf', download: 'annual-report-2024.pdf', ariaLabel: 'Download the 2024 Annual Report PDF', }, render: (args) => html` Download Annual Report (PDF) `, }; export const NavigationMenu: Story = { parameters: { controls: { disable: true }, // Static demo - no interactive controls needed }, render: () => html`

Navigation Menu

About Our Company Services & Programs News & Updates Contact Information

External Resources

External Site Partner Portal Support Center

Downloads

Download Policy Document Application Form (PDF)
`, }; export const AccessibilityExample: Story = { parameters: { controls: { disable: true }, // Static demo - no interactive controls needed }, render: () => html`

Accessibility Features Demo

This example shows proper link accessibility patterns for websites.

Application Form Additional Information Call Support: 1-800-555-0123 Email for Help: help@example.com Download Accessibility Policy (PDF, 245 KB)

Features demonstrated:

  • Descriptive aria-label attributes for context
  • External link indicators and security attributes
  • File type and size information for downloads
  • Keyboard accessibility (try Tab navigation)
  • Screen reader friendly link text
  • Proper focus indicators
`, }; export const EventHandling: Story = { parameters: { controls: { disable: true }, // Static demo - no interactive controls needed }, render: () => html`

Event Handling Demo

Click links to see custom events in the browser console.

{ console.log('Internal link clicked:', e.detail); e.preventDefault(); // Prevent navigation in demo alert(`Clicked: ${e.detail.href}`); }} > Internal Link (with event handling) { console.log('External link clicked:', e.detail); // Don't prevent default for external links in real apps alert(`External link: ${e.detail.href}\nWill open in new tab`); }} > External Link (with analytics tracking) { console.log('Download link clicked:', e.detail); alert(`Download started: ${e.detail.href}`); }} > Download Link (with tracking)

Event Details Available:

  • href: The link destination
  • target: The target window/frame
  • external: Boolean indicating external link
  • event: The original click event

Open browser console to see event details.

`, };