@fabio.caffarello/react-design-system 1.7.0 → 1.9.0

package/src/ui/atoms/NavLink/NavLink.test.tsx

@@ -1,44 +1,252 @@
-import { describe, it, expect } from "vitest";
-import { render, screen } from "@testing-library/react";
-import NavLink from "./NavLink";
+/**
+ * NavLink Tests
+ * 
+ * Unit tests for the NavLink component.
+ */
 
-describe("NavLink", () => {
-  it("renders as anchor with href", () => {
-    render(<NavLink href="/test">Test Link</NavLink>);
-    const link = screen.getByText("Test Link");
-    expect(link).toBeInTheDocument();
-    expect(link.tagName).toBe("A");
-    expect(link).toHaveAttribute("href", "/test");
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { NavLink } from './NavLink';
+
+describe('NavLink', () => {
+  describe('Rendering', () => {
+    it('renders with text', () => {
+      render(<NavLink href="/home">Home</NavLink>);
+      expect(screen.getByText('Home')).toBeInTheDocument();
+    });
+
+    it('renders as anchor tag by default', () => {
+      render(<NavLink href="/home">Home</NavLink>);
+      const link = screen.getByRole('link');
+      expect(link).toHaveAttribute('href', '/home');
+    });
+
+    it('renders with correct href', () => {
+      render(<NavLink href="/about">About</NavLink>);
+      const link = screen.getByRole('link');
+      expect(link).toHaveAttribute('href', '/about');
+    });
+  });
+
+  describe('Variants', () => {
+    it('applies default variant', () => {
+      const { container } = render(<NavLink href="/home">Home</NavLink>);
+      const link = container.querySelector('a');
+      expect(link).toBeInTheDocument();
+    });
+
+    it('applies underline variant', () => {
+      const { container } = render(
+        <NavLink href="/home" variant="underline">Home</NavLink>
+      );
+      const link = container.querySelector('a');
+      expect(link).toHaveClass('border-b-2');
+    });
+
+    it('applies background variant', () => {
+      const { container } = render(
+        <NavLink href="/home" variant="background">Home</NavLink>
+      );
+      const link = container.querySelector('a');
+      expect(link).toHaveClass('rounded-md');
+    });
+  });
+
+  describe('Sizes', () => {
+    it('applies sm size', () => {
+      const { container } = render(
+        <NavLink href="/home" size="sm">Home</NavLink>
+      );
+      const link = container.querySelector('a');
+      expect(link).toBeInTheDocument();
+    });
+
+    it('applies md size (default)', () => {
+      const { container } = render(<NavLink href="/home">Home</NavLink>);
+      const link = container.querySelector('a');
+      expect(link).toBeInTheDocument();
+    });
+
+    it('applies lg size', () => {
+      const { container } = render(
+        <NavLink href="/home" size="lg">Home</NavLink>
+      );
+      const link = container.querySelector('a');
+      expect(link).toBeInTheDocument();
+    });
   });
 
-  it("renders as span when disabled", () => {
-    render(<NavLink variant="disabled">Disabled Link</NavLink>);
-    const link = screen.getByText("Disabled Link");
-    expect(link.tagName).toBe("SPAN");
-    expect(link).toHaveAttribute("aria-disabled", "true");
+  describe('Active State', () => {
+    it('applies active classes when active', () => {
+      const { container } = render(
+        <NavLink href="/home" active>Home</NavLink>
+      );
+      const link = container.querySelector('a');
+      expect(link).toHaveAttribute('data-active', 'true');
+      expect(link).toHaveAttribute('aria-current', 'page');
+    });
+
+    it('does not apply active classes when not active', () => {
+      const { container } = render(<NavLink href="/home">Home</NavLink>);
+      const link = container.querySelector('a');
+      expect(link).not.toHaveAttribute('aria-current');
+    });
+
+    it('applies active styles for default variant', () => {
+      const { container } = render(
+        <NavLink href="/home" active variant="default">Home</NavLink>
+      );
+      const link = container.querySelector('a');
+      expect(link).toHaveAttribute('data-active', 'true');
+    });
+
+    it('applies active styles for underline variant', () => {
+      const { container } = render(
+        <NavLink href="/home" active variant="underline">Home</NavLink>
+      );
+      const link = container.querySelector('a');
+      expect(link).toHaveAttribute('data-active', 'true');
+    });
+
+    it('applies active styles for background variant', () => {
+      const { container } = render(
+        <NavLink href="/home" active variant="background">Home</NavLink>
+      );
+      const link = container.querySelector('a');
+      expect(link).toHaveAttribute('data-active', 'true');
+    });
   });
 
-  it("applies default variant classes", () => {
-    const { container } = render(<NavLink href="/test">Link</NavLink>);
-    const link = container.querySelector("a");
-    expect(link).toHaveClass("border-transparent", "text-gray-500");
+  describe('Disabled State', () => {
+    it('applies disabled classes when disabled', () => {
+      const { container } = render(
+        <NavLink href="/home" disabled>Home</NavLink>
+      );
+      const link = container.querySelector('a');
+      expect(link).toHaveAttribute('data-disabled', 'true');
+      expect(link).toHaveAttribute('aria-disabled', 'true');
+      expect(link).toHaveAttribute('tabIndex', '-1');
+    });
+
+    it('removes href when disabled', () => {
+      const { container } = render(<NavLink href="/home" disabled>Home</NavLink>);
+      const link = container.querySelector('a');
+      // When disabled, href is set to undefined in linkProps
+      // For anchor tags, undefined href means the attribute is not set or is empty
+      expect(link).toBeInTheDocument();
+      // Check that href is either not present or is empty/undefined
+      const hrefValue = link?.getAttribute('href');
+      expect(hrefValue === null || hrefValue === '' || hrefValue === 'undefined').toBe(true);
+    });
+
+    it('prevents click when disabled', () => {
+      const handleClick = vi.fn();
+      const { container } = render(
+        <NavLink href="/home" disabled onClick={handleClick}>
+          Home
+        </NavLink>
+      );
+      const link = container.querySelector('a');
+      if (link) {
+        fireEvent.click(link);
+      }
+      expect(handleClick).not.toHaveBeenCalled();
+    });
+
+    it('prevents keyboard activation when disabled', () => {
+      const handleKeyDown = vi.fn();
+      const { container } = render(
+        <NavLink href="/home" disabled onKeyDown={handleKeyDown}>
+          Home
+        </NavLink>
+      );
+      const link = container.querySelector('a');
+      if (link) {
+        fireEvent.keyDown(link, { key: 'Enter' });
+      }
+      expect(handleKeyDown).not.toHaveBeenCalled();
+    });
   });
 
-  it("applies active variant classes", () => {
-    const { container } = render(<NavLink href="/test" variant="active">Link</NavLink>);
-    const link = container.querySelector("a");
-    expect(link).toHaveClass("border-indigo-500", "text-gray-900");
+  describe('Accessibility', () => {
+    it('has aria-current when active', () => {
+      render(<NavLink href="/home" active>Home</NavLink>);
+      const link = screen.getByRole('link');
+      expect(link).toHaveAttribute('aria-current', 'page');
+    });
+
+    it('has aria-disabled when disabled', () => {
+      const { container } = render(<NavLink href="/home" disabled>Home</NavLink>);
+      const link = container.querySelector('a');
+      // When disabled with pointer-events-none, the element is not accessible via getByRole
+      // So we use container.querySelector and check attributes directly
+      expect(link).toBeInTheDocument();
+      expect(link).toHaveAttribute('aria-disabled', 'true');
+    });
+
+    it('supports aria-label', () => {
+      render(
+        <NavLink href="/home" aria-label="Navigate to home page">
+          Home
+        </NavLink>
+      );
+      const link = screen.getByLabelText('Navigate to home page');
+      expect(link).toBeInTheDocument();
+    });
+
+    it('has tabIndex -1 when disabled', () => {
+      const { container } = render(<NavLink href="/home" disabled>Home</NavLink>);
+      const link = container.querySelector('a');
+      expect(link).toHaveAttribute('tabIndex', '-1');
+    });
   });
 
-  it("applies disabled variant classes", () => {
-    const { container } = render(<NavLink variant="disabled">Link</NavLink>);
-    const link = container.querySelector("span");
-    expect(link).toHaveClass("text-gray-300", "cursor-not-allowed");
+  describe('Interactions', () => {
+    it('calls onClick when clicked', () => {
+      const handleClick = vi.fn();
+      render(
+        <NavLink href="/home" onClick={handleClick}>
+          Home
+        </NavLink>
+      );
+      fireEvent.click(screen.getByText('Home'));
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    it('calls onKeyDown when key pressed', () => {
+      const handleKeyDown = vi.fn();
+      render(
+        <NavLink href="/home" onKeyDown={handleKeyDown}>
+          Home
+        </NavLink>
+      );
+      fireEvent.keyDown(screen.getByText('Home'), { key: 'Enter' });
+      expect(handleKeyDown).toHaveBeenCalledTimes(1);
+    });
   });
 
-  it("applies custom className", () => {
-    const { container } = render(<NavLink href="/test" className="custom-class">Link</NavLink>);
-    const link = container.querySelector("a");
-    expect(link).toHaveClass("custom-class");
+  describe('Custom Element (as prop)', () => {
+    it('renders as custom element when as prop provided', () => {
+      const CustomLink = ({ 
+        href, 
+        children, 
+        ...props 
+      }: { 
+        href: string; 
+        children: React.ReactNode; 
+        [key: string]: unknown;
+      }) => (
+        <a href={href} data-custom="true" {...props}>
+          {children}
+        </a>
+      );
+      render(
+        <NavLink href="/home" as={CustomLink}>
+          Home
+        </NavLink>
+      );
+      const link = screen.getByText('Home');
+      expect(link).toHaveAttribute('data-custom', 'true');
+    });
   });
 });

package/src/ui/atoms/NavLink/NavLink.tsx

@@ -1,69 +1,282 @@
 'use client';
 
-import type { AnchorHTMLAttributes, ReactNode } from "react";
+/**
+ * NavLink Component
+ * 
+ * Navigation link component with active state detection and Next.js integration.
+ * 
+ * @see EPIC-001: NavLink Component (Atom)
+ * @see RFC-001: NavLink Hook Strategy (APPROVED)
+ * @see RFC-002: Next.js Integration Strategy (APPROVED)
+ * @see ADR-001: Active State Detection (ACCEPTED)
+ */
 
-export interface NavLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
-  variant?: "default" | "active" | "disabled";
-  icon?: ReactNode;
-  children: ReactNode;
-}
+import React, { useMemo, useCallback } from 'react';
+import type { NavLinkProps } from './types';
+import { useNavLink } from './hooks/useNavLink';
+import { cn, cva } from '../../utils';
+import { getColorClass, getHoverColorClass, getFocusRingClass } from '../../tokens/colors';
+import { getSpacingClass } from '../../tokens/spacing';
+import { getTypographySize } from '../../tokens/typography';
+import { getRadiusClass } from '../../tokens/radius';
+
+/**
+ * NavLink Variants using CVA
+ * Type-safe variant system for NavLink component
+ */
+const navLinkVariants = cva(
+  // Base classes
+  cn(
+    'inline-flex',
+    'items-center',
+    'transition-colors',
+    'focus:outline-none',
+    'focus:ring-2',
+    'focus:ring-offset-2',
+    'disabled:opacity-50',
+    'disabled:cursor-not-allowed',
+    'disabled:pointer-events-none',
+    'no-underline'
+  ),
+  {
+    variants: {
+      variant: {
+        default: cn(
+          getColorClass('neutral', 'dark', 'text'),
+          'hover:opacity-80',
+          'focus-visible:opacity-100',
+          getFocusRingClass('primary', 'DEFAULT')
+        ),
+        underline: cn(
+          getColorClass('neutral', 'dark', 'text'),
+          'hover:opacity-80',
+          'focus-visible:opacity-100',
+          'border-b-2',
+          'border-transparent',
+          'hover:border-current',
+          getFocusRingClass('primary', 'DEFAULT')
+        ),
+        background: cn(
+          getColorClass('neutral', 'dark', 'text'),
+          getHoverColorClass('neutral', 'light', 'bg'),
+          'rounded-md',
+          getRadiusClass('md'),
+          getFocusRingClass('primary', 'DEFAULT')
+        ),
+      },
+      size: {
+        sm: cn(
+          getSpacingClass('sm', 'px'),
+          getSpacingClass('xs', 'py'),
+          getTypographySize('bodySmall')
+        ),
+        md: cn(
+          getSpacingClass('base', 'px'),
+          getSpacingClass('sm', 'py'),
+          getTypographySize('body')
+        ),
+        lg: cn(
+          getSpacingClass('lg', 'px'),
+          getSpacingClass('md', 'py'),
+          getTypographySize('bodyLarge')
+        ),
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'md',
+    },
+    compoundVariants: [
+      {
+        variant: 'underline',
+        size: 'sm',
+        class: 'pb-0.5',
+      },
+      {
+        variant: 'underline',
+        size: 'md',
+        class: 'pb-1',
+      },
+      {
+        variant: 'underline',
+        size: 'lg',
+        class: 'pb-1.5',
+      },
+      {
+        variant: 'background',
+        size: 'sm',
+        class: getSpacingClass('xs', 'px'),
+      },
+      {
+        variant: 'background',
+        size: 'md',
+        class: getSpacingClass('sm', 'px'),
+      },
+      {
+        variant: 'background',
+        size: 'lg',
+        class: getSpacingClass('base', 'px'),
+      },
+    ],
+  }
+);
 
 /**
  * NavLink Component
  * 
- * A navigation link component with active and disabled states.
- * Follows Atomic Design principles as an Atom component.
+ * Navigation link with active state detection and Next.js integration.
  * 
  * @example
  * ```tsx
- * <NavLink href="/dashboard" variant="active">
- *   Dashboard
- * </NavLink>
+ * <NavLink href="/home">Home</NavLink>
+ * <NavLink href="/about" variant="underline" active>About</NavLink>
+ * <NavLink href="/contact" variant="background" size="lg">Contact</NavLink>
  * ```
+ * 
+ * Note: Auto-detection of active state via usePathname is deferred to a future enhancement
+ * to avoid issues with conditional hook calls. For now, use the `active` prop manually
+ * or implement pathname detection in the parent component.
  */
-export default function NavLink({
-  variant = "default",
-  icon,
-  className = "",
+export function NavLink({
+  href,
   children,
+  active,
+  disabled = false,
+  variant = 'default',
+  size = 'md',
+  as,
+  className,
+  'aria-label': ariaLabel,
+  onClick,
+  onKeyDown,
   ...props
 }: NavLinkProps) {
-  const baseClasses = [
-    "inline-flex",
-    "items-center",
-    "px-1",
-    "pt-1",
-    "border-b-2",
-    "text-sm",
-    "font-medium",
-    "transition-colors",
-  ];
-
-  const variantClasses: Record<NonNullable<NavLinkProps["variant"]>, string> = {
-    default: "border-transparent text-gray-500 hover:border-gray-300 hover:text-gray-700",
-    active: "border-indigo-500 text-gray-900",
-    disabled: "border-transparent text-gray-300 cursor-not-allowed pointer-events-none",
-  };
-
-  const classes = [
-    ...baseClasses,
-    variantClasses[variant],
-    className,
-  ].filter(Boolean).join(" ");
-
-  if (variant === "disabled") {
-    return (
-      <span className={classes} aria-disabled="true">
-        {icon && <span className="flex-shrink-0">{icon}</span>}
-        {children}
-      </span>
-    );
-  }
+  // Calculate active state
+  // Priority: manual active > false (ADR-001)
+  // TODO: Add auto-detect via usePathname in future enhancement
+  // This requires a wrapper component pattern to avoid conditional hook calls
+  const calculatedActive = useMemo(() => {
+    // Manual active prop has priority (ADR-001)
+    if (active !== undefined) {
+      return active;
+    }
 
-  return (
-    <a className={classes} {...props}>
-      {icon && <span className="flex-shrink-0">{icon}</span>}
-      {children}
-    </a>
+    // Default to false
+    // TODO: Auto-detect using usePathname (if Next.js available)
+    return false;
+  }, [active]);
+
+  // Use hook for Next.js Link integration
+  const { NextLink } = useNavLink({ href, active: calculatedActive });
+
+  // Determine Link component
+  // Priority: as prop > NextLink (auto-detected) > 'a' (RFC-002)
+  const LinkComponent: React.ElementType = as || NextLink || 'a';
+
+  // Active state classes
+  const activeClasses = useMemo(() => {
+    if (!calculatedActive) return '';
+
+    switch (variant) {
+      case 'underline':
+        return cn(
+          'border-b-2',
+          getColorClass('primary', 'DEFAULT', 'border'),
+          getColorClass('primary', 'DEFAULT', 'text')
+        );
+      case 'background':
+        return cn(
+          getColorClass('primary', 'light', 'bg'),
+          getColorClass('primary', 'DEFAULT', 'text')
+        );
+      case 'default':
+      default:
+        return cn(
+          getColorClass('primary', 'DEFAULT', 'text'),
+          'font-semibold'
+        );
+    }
+  }, [calculatedActive, variant]);
+
+  // Handle disabled state
+  const handleClick = useCallback(
+    (e: React.MouseEvent<HTMLAnchorElement>) => {
+      if (disabled) {
+        e.preventDefault();
+        e.stopPropagation();
+        return;
+      }
+      onClick?.(e);
+    },
+    [disabled, onClick]
+  );
+
+  // Handle keyboard navigation
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLAnchorElement>) => {
+      if (disabled) {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          e.stopPropagation();
+        }
+        return;
+      }
+      onKeyDown?.(e);
+    },
+    [disabled, onKeyDown]
   );
+
+  // Prepare props for LinkComponent
+  // Next.js Link has different prop structure, so we need to handle it
+  const linkProps = useMemo(() => {
+    const baseProps = {
+      className: cn(
+        navLinkVariants({ variant, size }),
+        activeClasses,
+        disabled && 'opacity-50 cursor-not-allowed pointer-events-none',
+        className
+      ),
+      'aria-current': calculatedActive ? 'page' : undefined,
+      'aria-disabled': disabled ? true : undefined,
+      'aria-label': ariaLabel,
+      tabIndex: disabled ? -1 : undefined,
+      onClick: handleClick,
+      onKeyDown: handleKeyDown,
+      'data-active': calculatedActive,
+      'data-disabled': disabled,
+      ...props,
+    };
+
+    // For Next.js Link, we need to pass href differently
+    if (NextLink && !as) {
+      return {
+        ...baseProps,
+        href: disabled ? undefined : href,
+      };
+    }
+
+    // For regular anchor or custom component
+    return {
+      ...baseProps,
+      href: disabled ? undefined : href,
+    };
+  }, [
+    variant,
+    size,
+    activeClasses,
+    disabled,
+    className,
+    calculatedActive,
+    ariaLabel,
+    handleClick,
+    handleKeyDown,
+    href,
+    NextLink,
+    as,
+    props,
+  ]);
+
+  return <LinkComponent {...linkProps}>{children}</LinkComponent>;
 }
+
+export default NavLink;