@ceed/ads 1.23.3 → 1.23.5

package/dist/components/navigation/Link.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-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.
+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.
 
 ```tsx
 <Link
@@ -27,15 +29,12 @@ import { Link } from '@ceed/ads';
 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>
@@ -44,22 +43,11 @@ function MyComponent() {
 }
 ```
 
-## Examples
-
-### Basic Link
-
-The default link appearance with plain variant.
-
-```tsx
-<Link
-  children="Link"
-  variant="plain"
-/>
-```
+## Features
 
 ### Variants
 
-Links support different visual styles through the variant prop.
+Links support four visual styles through the `variant` prop: `plain`, `outlined`, `soft`, and `solid`.
 
 ```tsx
 <div style={{
@@ -84,7 +72,7 @@ Links support different visual styles through the variant prop.
 
 ### Colors
 
-Apply different semantic colors to links.
+Apply semantic colors to communicate different purposes -- `primary`, `neutral`, `success`, `warning`, and `danger`.
 
 ```tsx
 <div style={{
@@ -112,7 +100,7 @@ Apply different semantic colors to links.
 
 ### Underline Styles
 
-Control the underline behavior of links.
+Control the underline behavior with three options: `none` (never shown), `hover` (shown on hover), and `always` (permanently visible).
 
 ```tsx
 <div style={{
@@ -134,7 +122,7 @@ Control the underline behavior of links.
 
 ### Typography Levels
 
-Links can inherit or specify typography levels for different text hierarchies.
+Links can adopt any typography level from the design system, enabling consistent text hierarchies when links appear alongside headings or body text.
 
 ```tsx
 <div style={{
@@ -172,7 +160,7 @@ Links can inherit or specify typography levels for different text hierarchies.
 
 ### Disabled State
 
-Links can be disabled to prevent interaction.
+Links can be disabled to prevent interaction while remaining visible in the layout.
 
 ```tsx
 <Link
@@ -185,7 +173,7 @@ Links can be disabled to prevent interaction.
 
 ### External Links
 
-Links to external resources with proper security attributes.
+For links that navigate away from your application, include `target="_blank"` and `rel="noopener noreferrer"` for security.
 
 ```tsx
 <Link href="https://example.com" target="_blank" rel="noopener noreferrer">
@@ -195,7 +183,7 @@ Links to external resources with proper security attributes.
 
 ### Inline with Text
 
-Links can be seamlessly integrated within paragraph text.
+Links integrate seamlessly within paragraph text, inheriting the surrounding font styles.
 
 ```tsx
 <p style={{
@@ -205,84 +193,23 @@ This is a paragraph with an <Link href="#">inline link</Link> that flows natural
 </p>
 ```
 
-## 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 about our services, please visit our{' '}
-      <Link href="/services">services page</Link> or read our{' '}
+      For more information, visit our{' '}
+      <Link href="/services">services page</Link> or read the{' '}
       <Link href="/faq">frequently asked questions</Link>.
     </Typography>
   );
 }
 ```
 
-### 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
+### Footer Navigation
 
 ```tsx
 function FooterLinks() {
@@ -302,12 +229,12 @@ function FooterLinks() {
 }
 ```
 
-### Link with React Router
+### Router Integration
 
 ```tsx
 import { Link as RouterLink } from 'react-router-dom';
 
-function RouterIntegration() {
+function AppNavigation() {
   return (
     <Link component={RouterLink} to="/dashboard">
       Go to Dashboard
@@ -316,235 +243,49 @@ function RouterIntegration() {
 }
 ```
 
-### Skip to Content Link
-
-```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
-<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
-
-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
+## Best Practices
 
-- Links announce their destination or purpose
-- Use descriptive link text instead of "click here" or "read more"
+- **Use descriptive link text.** The text should clearly communicate the destination. Avoid generic labels such as "click here" or "read more".
 
 ```tsx
-// ✅ Good: Descriptive link text
-<Link href="/pricing">View our pricing plans</Link>
+// Good
+<Link href="/pricing">View pricing plans</Link>
 
-// ❌ Bad: Non-descriptive link text
+// Bad
 <Link href="/pricing">Click here</Link>
 ```
 
-### 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:
+- **Indicate external links.** When a link opens in a new tab, add a visual cue (such as an icon) and the appropriate security attributes.
 
 ```tsx
-<Link
-  href="https://external-site.com"
-  target="_blank"
-  rel="noopener noreferrer"
-  aria-label="Visit external site (opens in new tab)"
->
-  External Site
+// Good
+<Link href="https://docs.example.com" target="_blank" rel="noopener noreferrer">
+  Documentation
 </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
 
-```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 }} />
+// Bad -- opens in new tab with no indication
+<Link href="https://docs.example.com" target="_blank">
+  Documentation
 </Link>
 ```
 
-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
+- **Do not use links for actions.** If clicking triggers a side effect (form submission, modal opening, deletion), use a Button component instead.
 
 ```tsx
-// ❌ Bad: Using link for action
-<Link onClick={handleSubmit}>Submit Form</Link>
-
-// ✅ Good: Using button for action
+// Good
 <Button onClick={handleSubmit}>Submit Form</Button>
-```
-
-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>
+// Bad
+<Link onClick={handleSubmit}>Submit Form</Link>
 ```
 
-### Avoid Unnecessary Re-renders
-
-For links in lists or frequently updating components, ensure stable references:
+- **Maintain visual consistency.** Use the same variant, color, and underline settings for links that serve the same purpose across different pages.
 
-```tsx
-// Using useCallback for event handlers in links
-const handleClick = useCallback((e) => {
-  trackLinkClick(e);
-}, []);
+- **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.
 
-<Link href="/page" onClick={handleClick}>
-  Tracked Link
-</Link>
-```
+## Accessibility
 
-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.
+- **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.