@ceed/cds 1.28.1 → 1.29.0-next.1

package/dist/components/navigation/Link.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-The Link component is a navigational element that allows users to move between pages or access external resources. Built on top of Joy UI's Link, it provides consistent styling, multiple visual variants, and comprehensive accessibility features out of the box.
-
-Links are fundamental to web navigation. Use them to connect related content, reference external documentation, or enable movement between sections of your application. For actions that do not navigate (such as submitting a form or opening a modal), use a Button instead.
+The Link component is a navigational element that allows users to navigate between pages or external resources. Built on Joy UI's Link, it provides consistent styling and accessibility features while supporting various visual styles and text hierarchy levels. Links are fundamental to web navigation and should be used to connect related content within your application.
 
 ```tsx
 <Link
@@ -29,12 +27,15 @@ import { Link } from '@ceed/cds';
 function MyComponent() {
   return (
     <div>
+      {/* Basic link */}
       <Link href="/about">About Us</Link>
 
+      {/* External link */}
       <Link href="https://example.com" target="_blank" rel="noopener noreferrer">
         External Site
       </Link>
 
+      {/* Styled link */}
       <Link href="/contact" color="primary" underline="hover">
         Contact
       </Link>
@@ -43,23 +44,153 @@ function MyComponent() {
 }
 ```
 
+## Examples
+
+### Basic Link
+
+The default link appearance with plain variant.
+
+```tsx
+<Link
+  children="Link"
+  variant="plain"
+/>
+```
+
+### Variants
+
+Links support different visual styles through the variant prop.
+
+```
+<Canvas of={Link.Variants} />
+```
+
+### Colors
+
+Apply different semantic colors to links.
+
+```
+<Canvas of={Link.Colors} />
+```
+
+### Underline Styles
+
+Control the underline behavior of links.
+
+```
+<Canvas of={Link.Underline} />
+```
+
+### Typography Levels
+
+Links can inherit or specify typography levels for different text hierarchies.
+
+```
+<Canvas of={Link.Levels} />
+```
+
+### Disabled State
+
+Links can be disabled to prevent interaction.
+
+```
+<Canvas of={Link.Disabled} />
+```
+
+### External Links
+
+Links to external resources with proper security attributes.
+
+```
+<Canvas of={Link.ExternalLink} />
+```
+
+### Inline with Text
+
+Links can be seamlessly integrated within paragraph text.
+
+```
+<Canvas of={Link.InlineWithText} />
+```
+
+## When to Use
+
+### ✅ Good Use Cases
+
+- **Page navigation**: Moving between different pages or sections within your app
+- **External resources**: Linking to external websites, documentation, or references
+- **In-context references**: Linking related content mentioned in text
+- **Skip navigation**: Accessibility links for keyboard users
+- **Breadcrumbs**: Navigation hierarchy indicators
+- **Footer navigation**: Site-wide links in footer sections
+
+### ❌ When Not to Use
+
+- **Actions that don't navigate**: Use Button instead for actions like submitting forms, opening modals, or triggering events
+- **Primary calls to action**: Use Button for prominent actions users should take
+- **Menu items**: Use MenuItem components within navigation menus
+- **Tab navigation**: Use Tabs component for content switching within a page
+- **Cards/clickable areas**: Use Card with onClick or a wrapping anchor element
+
 ## Common Use Cases
 
+### Navigation Menu Links
+
+```tsx
+function NavigationMenu() {
+  return (
+    <nav>
+      <Stack direction="row" spacing={3}>
+        <Link href="/" color="neutral" underline="none">
+          Home
+        </Link>
+        <Link href="/products" color="neutral" underline="none">
+          Products
+        </Link>
+        <Link href="/about" color="neutral" underline="none">
+          About
+        </Link>
+        <Link href="/contact" color="neutral" underline="none">
+          Contact
+        </Link>
+      </Stack>
+    </nav>
+  );
+}
+```
+
 ### Inline Text Links
 
 ```tsx
 function ArticleContent() {
   return (
     <Typography level="body-md">
-      For more information, visit our{' '}
-      <Link href="/services">services page</Link> or read the{' '}
+      For more information about our services, please visit our{' '}
+      <Link href="/services">services page</Link> or read our{' '}
       <Link href="/faq">frequently asked questions</Link>.
     </Typography>
   );
 }
 ```
 
-### Footer Navigation
+### External Links with Icon
+
+```tsx
+function ExternalResourceLink() {
+  return (
+    <Link
+      href="https://documentation.example.com"
+      target="_blank"
+      rel="noopener noreferrer"
+      endDecorator={<OpenInNewIcon sx={{ fontSize: 16 }} />}
+    >
+      View Documentation
+    </Link>
+  );
+}
+```
+
+### Footer Links
 
 ```tsx
 function FooterLinks() {
@@ -79,12 +210,12 @@ function FooterLinks() {
 }
 ```
 
-### Router Integration
+### Link with React Router
 
 ```tsx
 import { Link as RouterLink } from 'react-router-dom';
 
-function AppNavigation() {
+function RouterIntegration() {
   return (
     <Link component={RouterLink} to="/dashboard">
       Go to Dashboard
@@ -93,49 +224,235 @@ function AppNavigation() {
 }
 ```
 
-## Best Practices
+### Skip to Content Link
 
-- **Use descriptive link text.** The text should clearly communicate the destination. Avoid generic labels such as "click here" or "read more".
+```tsx
+function SkipLink() {
+  return (
+    <Link
+      href="#main-content"
+      sx={{
+        position: 'absolute',
+        left: '-9999px',
+        '&:focus': {
+          left: 0,
+          zIndex: 1000,
+          p: 2,
+          bgcolor: 'background.surface',
+        },
+      }}
+    >
+      Skip to main content
+    </Link>
+  );
+}
+```
+
+### Download Link
+
+```tsx
+function DownloadLink({ filename, url }) {
+  return (
+    <Link
+      href={url}
+      download={filename}
+      startDecorator={<DownloadIcon />}
+    >
+      Download {filename}
+    </Link>
+  );
+}
+```
+
+## Props and Customization
+
+### Key Props
+
+| Prop             | Type                                                           | Default     | Description                              |
+| ---------------- | -------------------------------------------------------------- | ----------- | ---------------------------------------- |
+| `href`           | `string`                                                       | -           | The URL to navigate to                   |
+| `variant`        | `'plain' \| 'outlined' \| 'soft' \| 'solid'`                   | `'plain'`   | Visual style variant                     |
+| `color`          | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'primary'` | Color scheme                             |
+| `level`          | `string`                                                       | -           | Typography level (e.g., 'body-md', 'h4') |
+| `underline`      | `'none' \| 'hover' \| 'always'`                                | `'hover'`   | Underline behavior                       |
+| `disabled`       | `boolean`                                                      | `false`     | Disable the link                         |
+| `startDecorator` | `ReactNode`                                                    | -           | Element before the link text             |
+| `endDecorator`   | `ReactNode`                                                    | -           | Element after the link text              |
+| `component`      | `ElementType`                                                  | `'a'`       | The root element type                    |
+
+### Underline Behavior
+
+```tsx
+<Stack spacing={2}>
+  {/* No underline */}
+  <Link underline="none" href="#">Never underlined</Link>
+
+  {/* Underline on hover (default) */}
+  <Link underline="hover" href="#">Underline on hover</Link>
+
+  {/* Always underlined */}
+  <Link underline="always" href="#">Always underlined</Link>
+</Stack>
+```
+
+### With Decorators
 
 ```tsx
-// Good
-<Link href="/pricing">View pricing plans</Link>
+<Stack spacing={2}>
+  <Link href="#" startDecorator={<HomeIcon />}>
+    Home
+  </Link>
+
+  <Link href="#" endDecorator={<ArrowForwardIcon />}>
+    Learn more
+  </Link>
+
+  <Link
+    href="https://external.com"
+    target="_blank"
+    endDecorator={<OpenInNewIcon sx={{ fontSize: '1rem' }} />}
+  >
+    External link
+  </Link>
+</Stack>
+```
+
+### Custom Styling
+
+```tsx
+<Link
+  href="#"
+  sx={{
+    fontWeight: 'bold',
+    transition: 'color 0.2s',
+    '&:hover': {
+      color: 'primary.600',
+    },
+  }}
+>
+  Custom styled link
+</Link>
+```
+
+## Accessibility
 
-// Bad
+Link components include comprehensive accessibility features:
+
+### Semantic HTML
+
+- Uses native `<a>` element by default for proper semantics
+- Supports custom components for router integration
+
+### Screen Reader Support
+
+- Links announce their destination or purpose
+- Use descriptive link text instead of "click here" or "read more"
+
+```tsx
+// ✅ Good: Descriptive link text
+<Link href="/pricing">View our pricing plans</Link>
+
+// ❌ Bad: Non-descriptive link text
 <Link href="/pricing">Click here</Link>
 ```
 
-- **Indicate external links.** When a link opens in a new tab, add a visual cue (such as an icon) and the appropriate security attributes.
+### Keyboard Navigation
+
+- **Tab**: Navigate to and from links
+- **Enter**: Activate the link
+- Links receive visible focus indicators
+
+### External Links
+
+Always include proper attributes for external links:
 
 ```tsx
-// Good
-<Link href="https://docs.example.com" target="_blank" rel="noopener noreferrer">
-  Documentation
+<Link
+  href="https://external-site.com"
+  target="_blank"
+  rel="noopener noreferrer"
+  aria-label="Visit external site (opens in new tab)"
+>
+  External Site
 </Link>
+```
+
+### Color Contrast
+
+All link colors meet WCAG contrast requirements. Avoid relying solely on color to indicate links - use underlines or other visual indicators.
+
+## Best Practices
+
+### ✅ Do
+
+1. **Use descriptive text**: Link text should describe the destination
 
-// Bad -- opens in new tab with no indication
-<Link href="https://docs.example.com" target="_blank">
-  Documentation
+```tsx
+// ✅ Good
+<Link href="/documentation">Read the documentation</Link>
+
+// ❌ Bad
+<Link href="/documentation">Click here</Link>
+```
+
+2. **Indicate external links**: Show users when links open in new tabs
+
+```tsx
+<Link href="https://external.com" target="_blank" rel="noopener noreferrer">
+  External Resource <OpenInNewIcon sx={{ fontSize: 14 }} />
 </Link>
 ```
 
-- **Do not use links for actions.** If clicking triggers a side effect (form submission, modal opening, deletion), use a Button component instead.
+3. **Use appropriate colors**: Match link colors to their context and importance
+
+4. **Maintain consistency**: Use consistent link styles throughout your application
+
+### ❌ Don't
+
+1. **Don't use links for actions**: Use Button for non-navigation actions
 
 ```tsx
-// Good
+// ❌ Bad: Using link for action
+<Link onClick={handleSubmit}>Submit Form</Link>
+
+// ✅ Good: Using button for action
 <Button onClick={handleSubmit}>Submit Form</Button>
+```
 
-// Bad
-<Link onClick={handleSubmit}>Submit Form</Link>
+2. **Don't disable links without reason**: If content is unavailable, explain why
+
+3. **Don't open all external links in new tabs**: Only do so when users might lose context
+
+4. **Don't use link styling for non-interactive elements**
+
+## Performance Considerations
+
+### Prefetching
+
+When using with routing libraries, consider implementing link prefetching for improved perceived performance:
+
+```tsx
+// With Next.js
+import NextLink from 'next/link';
+
+<Link component={NextLink} href="/page" prefetch>
+  Prefetched Page
+</Link>
 ```
 
-- **Maintain visual consistency.** Use the same variant, color, and underline settings for links that serve the same purpose across different pages.
+### Avoid Unnecessary Re-renders
 
-- **Match typography level to context.** When a link sits inside a heading or body text block, set its `level` prop to match the surrounding text for visual harmony.
+For links in lists or frequently updating components, ensure stable references:
 
-## Accessibility
+```tsx
+// Using useCallback for event handlers in links
+const handleClick = useCallback((e) => {
+  trackLinkClick(e);
+}, []);
+
+<Link href="/page" onClick={handleClick}>
+  Tracked Link
+</Link>
+```
 
-- **Semantic HTML**: Renders a native `<a>` element by default, ensuring proper semantics and browser behavior. The `component` prop allows substitution with router-specific elements.
-- **Descriptive text**: Screen readers announce the link text as the accessible name. Always write link text that makes sense out of context since screen reader users often navigate by listing all links on a page.
-- **Keyboard navigation**: Links are focusable with `Tab` and activated with `Enter`. Visible focus indicators are provided for keyboard users.
-- **External link attributes**: Always add `target="_blank"` together with `rel="noopener noreferrer"` on external links to prevent security vulnerabilities and provide an `aria-label` that mentions the new tab behavior when appropriate.
+Link is a fundamental navigation component that ensures consistent, accessible navigation throughout your application. Use it thoughtfully to create clear pathways for users to explore your content.