@fpkit/acss 0.5.13 → 0.6.0

package/src/components/link/link.scss

@@ -1,92 +1,145 @@
 @use '../../sass/mixins';
 
+/**
+ * Link Component Styles
+ *
+ * Provides accessible, customizable link styles using CSS custom properties.
+ * Supports standard text links, button-styled links, and pill variants.
+ *
+ * WCAG 2.1 AA Compliance:
+ * - Focus indicators meet 2.4.7 (3:1 contrast minimum)
+ * - Color contrast meets 1.4.3 (4.5:1 for normal text)
+ * - Uses :focus-visible for better UX (keyboard vs mouse)
+ */
+
 a[href] {
-  --link-decoration: none;
+  // Color & Typography
   --link-color: #085ab7;
+  --link-weight: 400;
+  --link-fs: 1rem;
+
+  // Text Decoration
+  --link-decoration: none;
+  --link-decoration-offset: 0.09375rem; // 1.5px converted to rem
+  --link-decoration-thickness: 0.0625rem; // 1px converted to rem
+  --link-skip-ink: auto;
+
+  // Background & Border
   --link-bg: transparent;
+  --link-radius: 0.25rem;
+
+  // Spacing (for button variants)
   --link-px: 0;
   --link-py: 0;
+
+  // Transitions
   --link-transition: all 0.75s ease-in-out;
-  --link-fs: 1rem;
-  --link-radius: 0.25rem;
-  --link-skip-ink: auto;
-  --link-decoration-offset: 1.5px;
-  --link-decoration-thickness: 3px;
-  --link-decoration: color: var(--link-color) var(--link-decoration-offset)
-    var(--link-decoration-thickness) var(--link-skip-ink);
-  --link-decoration-thickness: 3px;
-  --link-decoration: color: var(--link-color) var(--link-decoration-offset)
-    var(--link-decoration-thickness) var(--link-skip-ink);
 
+  // Focus Indicator (WCAG 2.4.7 - 3:1 contrast minimum)
+  --link-focus-color: currentColor;
+  --link-focus-width: 0.125rem; // 2px
+  --link-focus-offset: 0.125rem; // 2px
+  --link-focus-style: solid;
+
+  // Apply base styles
   color: var(--link-color);
   font-size: var(--link-fs);
+  font-weight: var(--link-weight);
   text-decoration: var(--link-decoration);
   text-underline-offset: var(--link-decoration-offset);
+  text-decoration-thickness: var(--link-decoration-thickness);
   text-decoration-skip-ink: var(--link-skip-ink);
   background-color: var(--link-bg);
   border-radius: var(--link-radius);
-  background-color: var(--link-bg);
-  border-radius: var(--link-radius);
-  font-weight: var(--link-weight);
+  transition: var(--link-transition);
 
+  // Ensure child elements inherit weight/style
   > i,
   > b {
     font-weight: var(--link-weight);
     font-style: normal;
   }
 
+  // Hover state - add underline for clarity
   &:hover {
     --link-decoration: underline;
   }
 
+  // Focus state - WCAG 2.4.7 compliant focus indicator
   &:focus {
-    outline: none;
+    outline: var(--link-focus-width) var(--link-focus-style)
+      var(--link-focus-color);
+    outline-offset: var(--link-focus-offset);
     --link-decoration: underline;
   }
 
+  // Focus-visible for better UX (only show outline on keyboard focus)
+  &:focus-visible {
+    outline: var(--link-focus-width) var(--link-focus-style)
+      var(--link-focus-color);
+    outline-offset: var(--link-focus-offset);
+  }
+
+  // Visited and active states
   &:visited,
   &:active {
     --link-color: currentColor;
   }
 
+  // Button-styled links (via <b> wrapper, data-btn attribute, or <i> for pill)
   &:has(> b),
-  &[data-link~='btn'],
+  &[data-btn],
   &:has(> i) {
     --link-button-color: var(--link-color);
     --link-bg: transparent;
     --link-decoration: none;
-    --link-border: 2px currentColor solid;
+    --link-border-width: 0.125rem; // 2px
+    --link-border-color: currentColor;
+    --link-border-style: solid;
     --link-fs: 0.9rem;
+
+    color: var(--link-button-color);
     background-color: var(--link-bg);
     font-style: normal;
     font-size: var(--link-fs);
-    color: var(--link-button-color);
     padding-inline: var(--link-fs);
     padding-block: calc(var(--link-fs) - 0.4rem);
     border-radius: var(--link-radius, 99rem);
     display: inline-flex;
-    outline: var(--link-border);
-    &:focus {
-      outline: var(--link-border);
+    align-items: center;
+    justify-content: center;
+    outline: var(--link-border-width) var(--link-border-color)
+      var(--link-border-style);
+
+    // Focus state for button links
+    &:focus,
+    &:focus-visible {
+      outline: var(--link-border-width) var(--link-border-color)
+        var(--link-border-style);
+      outline-offset: var(--link-focus-offset);
       --link-decoration: none;
     }
+
+    // Hover state for button links
     &:hover {
       --link-decoration: none;
     }
+
+    // Apply scale transition from mixins
     @include mixins.scale-transitions;
   }
+
+  // Pill variant (rounded corners)
   &[data-link~='pill'],
   &:has(> i) {
     --link-radius: 99rem;
     --link-decoration: none;
     font-style: normal;
+
     &:hover,
-    &:focus {
+    &:focus,
+    &:focus-visible {
       --link-decoration: none;
     }
   }
 }
-
-header > section {
-  width: auto;
-}

package/src/components/link/link.stories.tsx

@@ -1,71 +1,424 @@
 import { StoryObj, Meta } from "@storybook/react-vite";
-
-import { within, expect } from "storybook/test";
-
+import { within, expect, userEvent, fn } from "storybook/test";
+import { useRef, useEffect } from "react";
 import Link from "./link";
+import type { LinkProps } from "./link.types";
 import "../../styles/link/link.css";
 
-const meta: Meta<typeof Link> = {
+const meta = {
   title: "FP.React Components/Links",
-  tags: ["version:1.0.0"],
+  tags: ["version:1.0.0", "autodocs"],
   component: Link,
   args: {
     href: "/",
     children: "Link",
   },
-} as Meta;
+  argTypes: {
+    href: {
+      control: "text",
+      description: "The URL the link points to",
+    },
+    target: {
+      control: "select",
+      options: ["_self", "_blank", "_parent", "_top"],
+      description: "Where to open the linked URL",
+    },
+    rel: {
+      control: "text",
+      description: "Relationship between current and linked document",
+    },
+    prefetch: {
+      control: "boolean",
+      description: "Hint to browser to prefetch the resource",
+    },
+    btnStyle: {
+      control: "text",
+      description: "Apply button styling to the link",
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A semantic, accessible anchor component with enhanced security for external links and flexible styling variants.",
+      },
+    },
+  },
+} as Meta<typeof Link>;
 
 export default meta;
-type Story = StoryObj<typeof Link>;
+type Story = StoryObj<LinkProps>;
 
-export const LinkComponent: Story = {
-  args: {},
-  play: async ({ canvasElement }) => {
+/**
+ * Basic link component with default styling.
+ * Links should have descriptive text that makes sense out of context.
+ */
+export const Default: Story = {
+  args: {
+    href: "/about",
+    children: "About Us",
+  },
+  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
     const canvas = within(canvasElement);
     const link = canvas.getByRole("link");
+
+    // Verify basic rendering
     expect(link).toBeInTheDocument();
-    expect(link).toHaveTextContent("Link");
+    expect(link).toHaveTextContent("About Us");
+    expect(link).toHaveAttribute("href", "/about");
+
+    // Verify accessibility
+    expect(link).toBeVisible();
+    expect(link.tagName).toBe("A");
   },
 };
 
+/**
+ * External link with automatic security attributes.
+ * The component automatically adds rel="noopener noreferrer" for target="_blank".
+ */
 export const ExternalLink: Story = {
   args: {
     href: "https://www.google.com",
     target: "_blank",
-    rel: "noopener noreferrer",
-    prefetch: true,
-    children: "Google",
+    children: "Visit Google",
   },
-  play: async ({ canvasElement }) => {
+  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
     const canvas = within(canvasElement);
     const link = canvas.getByRole("link");
+
+    // Verify external link attributes
     expect(link).toBeInTheDocument();
-    expect(link).toHaveTextContent("Google");
+    expect(link).toHaveTextContent("Visit Google");
     expect(link).toHaveAttribute("href", "https://www.google.com");
     expect(link).toHaveAttribute("target", "_blank");
-    expect(link).toHaveAttribute("rel", "noopener noreferrer prefetch");
+
+    // Verify automatic security attributes
+    const rel = link.getAttribute("rel");
+    expect(rel).toContain("noopener");
+    expect(rel).toContain("noreferrer");
   },
-} as Story;
+};
 
-export const ButtonLink: Story = {
+/**
+ * External link with prefetch hint.
+ * Combines security attributes with performance optimization.
+ */
+export const ExternalLinkWithPrefetch: Story = {
   args: {
-    ...LinkComponent.args,
-    children: <b>Button Link</b>,
+    href: "https://example.com/next-page",
+    target: "_blank",
+    prefetch: true,
+    children: "Prefetch Example",
+  },
+  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+    const canvas = within(canvasElement);
+    const link = canvas.getByRole("link");
+
+    // Verify prefetch is included with security
+    const rel = link.getAttribute("rel");
+    expect(rel).toContain("noopener");
+    expect(rel).toContain("noreferrer");
+    expect(rel).toContain("prefetch");
   },
-} as Story;
+};
 
-export const ButtonPill: Story = {
+/**
+ * External link with custom rel attributes.
+ * Custom rel values are merged with security defaults, not overwritten.
+ */
+export const ExternalLinkWithCustomRel: Story = {
   args: {
-    ...LinkComponent.args,
-    children: <i>Button Link</i>,
+    href: "https://example.com",
+    target: "_blank",
+    rel: "nofollow author",
+    children: "External Link with Custom Rel",
   },
-} as Story;
+  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+    const canvas = within(canvasElement);
+    const link = canvas.getByRole("link");
 
-export const ButtonRounded: Story = {
+    // Verify all rel tokens are present (merged, not replaced)
+    const rel = link.getAttribute("rel");
+    expect(rel).toContain("noopener");
+    expect(rel).toContain("noreferrer");
+    expect(rel).toContain("nofollow");
+    expect(rel).toContain("author");
+  },
+};
+
+/**
+ * Button-styled link using <b> wrapper.
+ * Maintains semantic <a> element while applying button appearance.
+ */
+export const ButtonStyled: Story = {
+  args: {
+    href: "/signup",
+    children: <b>Sign Up Now</b>,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Wrapping link text in `<b>` automatically applies button styling. This is useful for call-to-action links.",
+      },
+    },
+  },
+};
+
+/**
+ * Pill-styled button link using <i> wrapper.
+ * Applies rounded pill styling with button appearance.
+ */
+export const PillStyled: Story = {
+  args: {
+    href: "/get-started",
+    children: <i>Get Started</i>,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Wrapping link text in `<i>` applies pill (fully rounded) button styling.",
+      },
+    },
+  },
+};
+
+/**
+ * Button-styled link with custom border radius.
+ * Demonstrates CSS custom property override.
+ */
+export const ButtonWithCustomRadius: Story = {
   args: {
-    ...ButtonLink.args,
+    href: "/action",
+    children: <b>Custom Radius</b>,
     styles: {
-      "--link-radius": "initial",
+      "--link-radius": "0.5rem",
+    } as React.CSSProperties,
+  },
+};
+
+/**
+ * Link with custom color using CSS variables.
+ * All styling is controlled via CSS custom properties.
+ */
+export const CustomColor: Story = {
+  args: {
+    href: "/products",
+    children: "Browse Products",
+    styles: {
+      "--link-color": "#d63384",
+      "--link-decoration": "underline",
+    } as React.CSSProperties,
+  },
+};
+
+/**
+ * Keyboard navigation test.
+ * Verifies link is keyboard accessible with proper focus indicators.
+ */
+export const KeyboardNavigation: Story = {
+  args: {
+    href: "/keyboard-test",
+    children: "Keyboard Accessible Link",
+  },
+  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+    const canvas = within(canvasElement);
+    const link = canvas.getByRole("link");
+
+    // Tab to the link
+    await userEvent.tab();
+
+    // Verify focus
+    expect(link).toHaveFocus();
+
+    // Verify the link is announced by screen readers
+    expect(link).toHaveAccessibleName("Keyboard Accessible Link");
+  },
+};
+
+/**
+ * Icon-only link with aria-label.
+ * Demonstrates accessible pattern for icon-only links.
+ */
+export const IconOnlyWithAriaLabel: Story = {
+  args: {
+    href: "/settings",
+    "aria-label": "Open settings",
+    children: (
+      <svg
+        aria-hidden="true"
+        width="16"
+        height="16"
+        viewBox="0 0 16 16"
+        fill="currentColor"
+      >
+        <path d="M8 4.754a3.246 3.246 0 1 0 0 6.492 3.246 3.246 0 0 0 0-6.492zM5.754 8a2.246 2.246 0 1 1 4.492 0 2.246 2.246 0 0 1-4.492 0z" />
+        <path d="M9.796 1.343c-.527-1.79-3.065-1.79-3.592 0l-.094.319a.873.873 0 0 1-1.255.52l-.292-.16c-1.64-.892-3.433.902-2.54 2.541l.159.292a.873.873 0 0 1-.52 1.255l-.319.094c-1.79.527-1.79 3.065 0 3.592l.319.094a.873.873 0 0 1 .52 1.255l-.16.292c-.892 1.64.901 3.434 2.541 2.54l.292-.159a.873.873 0 0 1 1.255.52l.094.319c.527 1.79 3.065 1.79 3.592 0l.094-.319a.873.873 0 0 1 1.255-.52l.292.16c1.64.893 3.434-.902 2.54-2.541l-.159-.292a.873.873 0 0 1 .52-1.255l.319-.094c1.79-.527 1.79-3.065 0-3.592l-.319-.094a.873.873 0 0 1-.52-1.255l.16-.292c.893-1.64-.902-3.433-2.541-2.54l-.292.159a.873.873 0 0 1-1.255-.52l-.094-.319z" />
+      </svg>
+    ),
+  },
+  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+    const canvas = within(canvasElement);
+    const link = canvas.getByRole("link");
+
+    // Verify accessible name from aria-label
+    expect(link).toHaveAccessibleName("Open settings");
+
+    // Verify SVG is hidden from screen readers
+    const svg = link.querySelector("svg");
+    expect(svg).toHaveAttribute("aria-hidden", "true");
+  },
+};
+
+/**
+ * Skip link pattern with ref forwarding.
+ * Demonstrates programmatic focus management for accessibility.
+ */
+export const SkipLink: Story = {
+  render: () => {
+    const SkipLinkExample = () => {
+      const mainRef = useRef<HTMLAnchorElement>(null);
+
+      useEffect(() => {
+        // Simulate focus on mount (for demonstration)
+        const timer = setTimeout(() => {
+          mainRef.current?.focus();
+        }, 100);
+
+        return () => clearTimeout(timer);
+      }, []);
+
+      return (
+        <div style={{ padding: "1rem" }}>
+          <Link ref={mainRef} href="#main-content">
+            Skip to main content
+          </Link>
+          <p id="main-content" style={{ marginTop: "1rem" }}>
+            Main content starts here
+          </p>
+        </div>
+      );
+    };
+
+    return <SkipLinkExample />;
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Demonstrates ref forwarding for programmatic focus management. Useful for skip links and keyboard navigation patterns.",
+      },
     },
   },
-} as Story;
+};
+
+/**
+ * Email link (mailto:).
+ * Demonstrates non-HTTP URL schemes.
+ */
+export const EmailLink: Story = {
+  args: {
+    href: "mailto:hello@example.com",
+    children: "Contact us via email",
+  },
+};
+
+/**
+ * Phone link (tel:).
+ * Demonstrates telephone URL scheme.
+ */
+export const PhoneLink: Story = {
+  args: {
+    href: "tel:+1234567890",
+    children: "Call us: +1 (234) 567-890",
+  },
+};
+
+/**
+ * Link with onClick event handler (RECOMMENDED).
+ * onClick fires for all activation methods including keyboard.
+ */
+export const WithOnClick: Story = {
+  args: {
+    href: "/products",
+    children: "Track All Activations",
+    onClick: fn(),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "**Recommended**: Use `onClick` for analytics and tracking. It captures mouse clicks, touch events, AND keyboard activation (Enter key).",
+      },
+    },
+  },
+  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+    const canvas = within(canvasElement);
+    const link = canvas.getByRole("link");
+
+    // Click with mouse
+    await userEvent.click(link);
+
+    // Also works with keyboard
+    link.focus();
+    await userEvent.keyboard("{Enter}");
+
+    // Check console for both events
+  },
+};
+
+/**
+ * Link with onPointerDown event handler.
+ * Only fires for pointer events (mouse, touch, pen) - NOT keyboard.
+ */
+export const WithOnPointerDown: Story = {
+  args: {
+    href: "/products",
+    children: "Track Pointer Only",
+    onPointerDown: fn(),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "⚠️ **Accessibility Note**: `onPointerDown` does NOT fire for keyboard activation (Enter key). Use `onClick` if you need to track keyboard users.",
+      },
+    },
+  },
+  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+    const canvas = within(canvasElement);
+    const link = canvas.getByRole("link");
+
+    // Click with mouse - handler fires
+    await userEvent.click(link);
+
+    // Keyboard activation - handler does NOT fire
+    link.focus();
+    await userEvent.keyboard("{Enter}");
+
+    // Check console - only one event logged (mouse click)
+  },
+};
+
+/**
+ * Link with both onClick and onPointerDown.
+ * Demonstrates using both handlers together for comprehensive tracking.
+ */
+export const WithBothHandlers: Story = {
+  args: {
+    href: "/products",
+    children: "Track Both Ways",
+    onClick: fn(),
+    onPointerDown: fn(),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Use both handlers when you need comprehensive tracking: `onClick` captures all activations, while `onPointerDown` provides pointer-specific data.",
+      },
+    },
+  },
+};