@tpzdsp/next-toolkit 1.13.0 → 1.14.0

package/src/components/InfoBox/InfoBox.tsx

@@ -1,26 +1,29 @@
 'use client';
 
-import { type ReactNode, useRef, useId, type RefObject } from 'react';
+import { type ReactNode, useRef, useId, useState } from 'react';
 
-import { FocusTrap } from 'focus-trap-react';
-import { createPortal } from 'react-dom';
 import { FaInfoCircle } from 'react-icons/fa';
 
-import { useInfoBoxPosition, useInfoBoxState, usePortalMount } from './hooks';
-import type { Position } from './types';
-import { getTransformClasses, getFocusTrapConfig } from './utils';
+import {
+  useFloating,
+  autoUpdate,
+  offset,
+  flip,
+  shift,
+  arrow,
+  useClick,
+  useDismiss,
+  useRole,
+  useInteractions,
+  FloatingArrow,
+  FloatingFocusManager,
+  FloatingPortal,
+  type Placement,
+} from '@floating-ui/react';
+
 import type { ExtendProps } from '../../types';
 import { cn } from '../../utils';
 
-// Re-export position constants for consumer convenience
-export {
-  POSITION_TOP_LEFT,
-  POSITION_TOP_RIGHT,
-  POSITION_BOTTOM_LEFT,
-  POSITION_BOTTOM_RIGHT,
-} from './types';
-export type { Position } from './types';
-
 type Props = {
   /** Optional title displayed at the top of the info box content */
   title?: string;
@@ -34,8 +37,8 @@ type Props = {
   maxWidth?: string;
   /** Custom aria-label for the trigger button (default: 'Show information') */
   triggerLabel?: string;
-  /** Force a specific position instead of auto-calculating */
-  position?: Position;
+  /** Preferred placement (Floating UI will auto-adjust if needed) */
+  placement?: Placement;
 };
 
 export type InfoBoxProps = ExtendProps<'div', Props>;
@@ -47,43 +50,39 @@ export const InfoBox = ({
   onOpenChange,
   maxWidth = '320px',
   triggerLabel = 'Show information',
-  position: forcedPosition,
+  placement = 'bottom-start',
   className,
   ...props
 }: InfoBoxProps) => {
-  const triggerRef = useRef<HTMLButtonElement>(null);
-  const contentRef = useRef<HTMLDialogElement>(null);
+  const [isOpen, setIsOpen] = useState(defaultOpen);
+  const arrowRef = useRef(null);
+
+  const { refs, floatingStyles, context } = useFloating({
+    open: isOpen,
+    onOpenChange: (open) => {
+      setIsOpen(open);
+      onOpenChange?.(open);
+    },
+    placement,
+    middleware: [
+      offset(12), // Distance from trigger
+      flip(), // Flip to opposite side if not enough space
+      shift({ padding: 8 }), // Shift along the axis to stay in viewport
+      arrow({ element: arrowRef }), // Arrow pointing to trigger
+    ],
+    whileElementsMounted: autoUpdate, // Update position on scroll/resize
+  });
+
+  const click = useClick(context);
+  const dismiss = useDismiss(context);
+  const role = useRole(context);
+
+  const { getReferenceProps, getFloatingProps } = useInteractions([click, dismiss, role]);
 
   const triggerId = useId();
   const contentId = useId();
   const titleId = useId();
 
-  // Custom hooks for separation of concerns
-  const isMounted = usePortalMount();
-  const {
-    isOpen,
-    isTrapActive,
-    setIsTrapActive,
-    isOpenRef,
-    deactivatedByClick,
-    handleClose,
-    toggleOpen,
-  } = useInfoBoxState({ defaultOpen, onOpenChange });
-  const { calculatedPosition, contentPosition } = useInfoBoxPosition({
-    isOpen,
-    triggerRef: triggerRef as RefObject<HTMLElement | null>,
-    forcedPosition,
-  });
-
-  const focusTrapConfig = getFocusTrapConfig({
-    isOpenRef,
-    deactivatedByClick,
-    triggerRef: triggerRef as RefObject<HTMLElement | null>,
-    contentRef: contentRef as RefObject<HTMLElement | null>,
-    handleClose,
-    setIsTrapActive,
-  });
-
   const triggerClasses = cn(
     // Base styles - button structure only
     'inline-flex items-center justify-center',
@@ -107,18 +106,11 @@ export const InfoBox = ({
   );
 
   const contentClasses = cn(
-    // Position
-    'fixed',
     // Base styles
     'bg-white rounded-lg shadow-lg border border-gray-200',
     'p-4',
     // Width constraints
     'min-w-[280px]',
-    // Animation
-    'transition-all duration-200 ease-out',
-    isOpen ? 'opacity-100 scale-100' : 'opacity-0 scale-95 pointer-events-none',
-    // Transform based on position
-    getTransformClasses(calculatedPosition),
     // Z-index
     'z-50',
   );
@@ -126,37 +118,36 @@ export const InfoBox = ({
   return (
     <div className={cn('relative inline-flex', className)} {...props}>
       <button
-        ref={triggerRef}
+        ref={refs.setReference}
         id={triggerId}
         type="button"
         aria-expanded={isOpen}
         aria-controls={contentId}
         aria-haspopup="dialog"
         aria-label={triggerLabel}
-        onClick={toggleOpen}
         className={triggerClasses}
+        {...getReferenceProps()}
       >
         <FaInfoCircle className={iconClasses} aria-hidden="true" />
       </button>
 
-      {isMounted &&
-        isOpen &&
-        createPortal(
-          <FocusTrap active={isTrapActive} focusTrapOptions={focusTrapConfig}>
-            <dialog
-              ref={contentRef}
+      {isOpen && (
+        <FloatingPortal>
+          <FloatingFocusManager context={context} modal={false}>
+            <div
+              ref={refs.setFloating}
               id={contentId}
-              open
               aria-labelledby={title ? titleId : undefined}
               aria-label={title ? undefined : 'Information'}
-              tabIndex={-1}
               style={{
-                top: contentPosition.top,
-                left: contentPosition.left,
+                ...floatingStyles,
                 maxWidth: `min(${maxWidth}, calc(100vw - 32px))`,
               }}
               className={contentClasses}
+              {...getFloatingProps()}
             >
+              <FloatingArrow ref={arrowRef} context={context} className="fill-white" />
+
               {title ? (
                 <h2 id={titleId} className="text-sm font-semibold text-gray-900 mb-2">
                   {title}
@@ -168,10 +159,10 @@ export const InfoBox = ({
               >
                 {children}
               </div>
-            </dialog>
-          </FocusTrap>,
-          document.body,
-        )}
+            </div>
+          </FloatingFocusManager>
+        </FloatingPortal>
+      )}
     </div>
   );
 };

package/src/components/LinkButton/LinkButton.stories.tsx

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { LinkButton } from './LinkButton';
+
+const meta = {
+  title: 'Components/LinkButton',
+  component: LinkButton,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'inverse'],
+    },
+    openInNewTab: {
+      control: 'boolean',
+    },
+  },
+} satisfies Meta<typeof LinkButton>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Primary: Story = {
+  args: {
+    children: 'Explore data',
+    href: '/explore',
+    variant: 'primary',
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    children: 'Learn more',
+    href: '/about',
+    variant: 'secondary',
+  },
+};
+
+export const Inverse: Story = {
+  args: {
+    children: 'Get started',
+    href: '/start',
+    variant: 'inverse',
+  },
+};
+
+export const ExternalLink: Story = {
+  args: {
+    children: 'Visit GOV.UK',
+    href: 'https://www.gov.uk',
+    variant: 'primary',
+  },
+};
+
+export const OpenInNewTab: Story = {
+  args: {
+    children: 'Open in new tab',
+    href: '/internal-page',
+    variant: 'primary',
+    openInNewTab: true,
+  },
+};
+
+export const WithCustomStyling: Story = {
+  args: {
+    children: 'Custom styled button',
+    href: '/custom',
+    variant: 'primary',
+    className: 'px-8 py-4 text-xl',
+  },
+};

package/src/components/LinkButton/LinkButton.test.tsx

@@ -0,0 +1,177 @@
+import { LinkButton } from './LinkButton';
+import { render, screen } from '../../test/renderers';
+
+// Mock next/link
+vi.mock('next/link', () => ({
+  default: ({
+    href,
+    children,
+    className,
+    ...props
+  }: {
+    href: string;
+    children: React.ReactNode;
+    className?: string;
+  }) => (
+    <a href={href} className={className} data-testid="next-link" {...props}>
+      {children}
+    </a>
+  ),
+}));
+
+describe('LinkButton', () => {
+  describe('rendering', () => {
+    it('should render with children', () => {
+      render(<LinkButton href="/test">Click me</LinkButton>);
+
+      expect(screen.getByRole('link', { name: 'Click me' })).toBeInTheDocument();
+    });
+
+    it('should render as a link with correct href', () => {
+      render(<LinkButton href="/explore">Explore</LinkButton>);
+
+      const link = screen.getByRole('link', { name: 'Explore' });
+
+      expect(link).toHaveAttribute('href', '/explore');
+    });
+
+    it('should apply primary variant by default', () => {
+      render(<LinkButton href="/test">Button</LinkButton>);
+
+      const link = screen.getByRole('link');
+
+      expect(link).toHaveClass('bg-brand');
+    });
+
+    it('should apply secondary variant when specified', () => {
+      render(
+        <LinkButton href="/test" variant="secondary">
+          Button
+        </LinkButton>,
+      );
+
+      const link = screen.getByRole('link');
+
+      expect(link).toHaveClass('bg-slate-100');
+    });
+
+    it('should apply inverse variant when specified', () => {
+      render(
+        <LinkButton href="/test" variant="inverse">
+          Button
+        </LinkButton>,
+      );
+
+      const link = screen.getByRole('link');
+
+      expect(link).toHaveClass('bg-white');
+    });
+
+    it('should merge custom className', () => {
+      render(
+        <LinkButton href="/test" className="custom-class">
+          Button
+        </LinkButton>,
+      );
+
+      const link = screen.getByRole('link');
+
+      expect(link).toHaveClass('custom-class');
+      expect(link).toHaveClass('bg-brand'); // Still has base classes
+    });
+  });
+
+  describe('external links', () => {
+    it('should automatically detect external URLs', () => {
+      render(<LinkButton href="https://example.com">External</LinkButton>);
+
+      const link = screen.getByRole('link');
+
+      expect(link).toHaveAttribute('target', '_blank');
+      expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+    });
+
+    it('should detect protocol-relative URLs as external', () => {
+      render(<LinkButton href="//example.com">External</LinkButton>);
+
+      const link = screen.getByRole('link');
+
+      expect(link).toHaveAttribute('target', '_blank');
+    });
+
+    it('should detect mailto links as external', () => {
+      render(<LinkButton href="mailto:test@example.com">Email</LinkButton>);
+
+      const link = screen.getByRole('link');
+
+      expect(link).toHaveAttribute('target', '_blank');
+    });
+
+    it('should use Next.js Link for internal URLs', () => {
+      render(<LinkButton href="/internal">Internal</LinkButton>);
+
+      expect(screen.getByTestId('next-link')).toBeInTheDocument();
+
+      const link = screen.getByRole('link');
+
+      expect(link).not.toHaveAttribute('target');
+      expect(link).not.toHaveAttribute('rel');
+    });
+  });
+
+  describe('openInNewTab', () => {
+    it('should open in new tab when openInNewTab is true', () => {
+      render(
+        <LinkButton href="/internal" openInNewTab>
+          Open in new tab
+        </LinkButton>,
+      );
+
+      const link = screen.getByRole('link');
+
+      expect(link).toHaveAttribute('target', '_blank');
+      expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+    });
+
+    it('should use regular anchor tag when openInNewTab is true', () => {
+      render(
+        <LinkButton href="/internal" openInNewTab>
+          Open in new tab
+        </LinkButton>,
+      );
+
+      // Should not use Next.js Link when opening in new tab
+      expect(screen.queryByTestId('next-link')).not.toBeInTheDocument();
+    });
+
+    it('should not open in new tab by default for internal links', () => {
+      render(<LinkButton href="/internal">Internal</LinkButton>);
+
+      const link = screen.getByRole('link');
+
+      expect(link).not.toHaveAttribute('target');
+    });
+  });
+
+  describe('accessibility', () => {
+    it('should have link role', () => {
+      render(<LinkButton href="/test">Button</LinkButton>);
+
+      const link = screen.getByRole('link');
+
+      expect(link).toBeInTheDocument();
+    });
+
+    it('should accept aria attributes', () => {
+      render(
+        <LinkButton href="/test" aria-label="Custom label">
+          Button
+        </LinkButton>,
+      );
+
+      const link = screen.getByRole('link', { name: 'Custom label' });
+
+      expect(link).toBeInTheDocument();
+    });
+  });
+});

package/src/components/LinkButton/LinkButton.tsx

@@ -0,0 +1,80 @@
+import type { ReactNode } from 'react';
+
+import NextLink from 'next/link';
+
+import type { ExtendProps } from '../../types/utils';
+import { cn } from '../../utils';
+
+type Props = {
+  /** URL to navigate to */
+  href: string;
+  /** Button variant styling */
+  variant?: 'primary' | 'secondary' | 'inverse';
+  /** Content to display in the button */
+  children: ReactNode;
+  /** Whether to open in a new tab (default: false) */
+  openInNewTab?: boolean;
+};
+
+export type LinkButtonProps = ExtendProps<'a', Props>;
+
+const VARIANTS = {
+  primary: 'bg-brand hover-enabled:bg-green-600 text-white',
+  secondary: 'bg-slate-100 hover-enabled:bg-slate-200 text-black',
+  inverse: 'bg-white hover-enabled:bg-slate-50 text-brand',
+};
+
+/**
+ * Determines if a URL is external (different origin or absolute URL)
+ */
+const isExternalUrl = (href: string): boolean => {
+  // Absolute URLs (http://, https://, //)
+  if (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('//')) {
+    return true;
+  }
+
+  // mailto:, tel:, etc.
+  if (href.includes(':')) {
+    return true;
+  }
+
+  return false;
+};
+
+// NOTE: some of the styles are applied in `tailwind.css`, under `Button Styles`
+export const LinkButton = ({
+  href,
+  variant = 'primary',
+  openInNewTab = false,
+  className,
+  children,
+  ...props
+}: LinkButtonProps) => {
+  const buttonClasses = cn(
+    `sm:w-auto text-lg relative inline-flex w-full outline-none items-center border-transparent
+    justify-center border-2 text-center active-enabled:translate-y-[2px] focus:shadow-focus
+    focus:border-focus focus:shadow-[inset_0_0_0_1px] focus-idle:border-focus
+    focus-idle:text-focus-text focus-idle:bg-focus focus-idle:shadow-border-input
+    disabled:opacity-50 disabled:hover:cursor-not-allowed button`,
+    VARIANTS[variant],
+    className,
+  );
+
+  const isExternal = isExternalUrl(href);
+
+  // External link or forced new tab - use <a> tag with appropriate attributes
+  if (isExternal || openInNewTab) {
+    return (
+      <a href={href} target="_blank" rel="noopener noreferrer" className={buttonClasses} {...props}>
+        {children}
+      </a>
+    );
+  }
+
+  // Internal link - use Next.js Link for client-side navigation
+  return (
+    <NextLink href={href} className={buttonClasses} {...props}>
+      {children}
+    </NextLink>
+  );
+};

package/src/components/index.ts

@@ -1,6 +1,7 @@
 // Default components - these can be used in server or client-side rendering
 export { BackToTop } from './backToTop/BackToTop';
 export { Button } from './Button/Button';
+export { ButtonLink } from './ButtonLink/ButtonLink';
 export { Card } from './Card/Card';
 export { Chip } from './chip/Chip';
 export { CookieBanner } from './cookieBanner/CookieBanner';
@@ -16,6 +17,7 @@ export { EaLogo } from './images/EaLogo';
 export { OglLogo } from './images/OglLogo';
 export { ExternalLink } from './link/ExternalLink';
 export { Link } from './link/Link';
+export { LinkButton } from './LinkButton/LinkButton';
 export { Paragraph } from './Paragraph/Paragraph';
 export { RuleDivider } from './divider/RuleDivider';
 export { SkipLink } from './skipLink/SkipLink';
@@ -25,6 +27,7 @@ export { TextArea } from './form/TextArea';
 // Export default component types
 export type { BackToTopProps } from './backToTop/BackToTop';
 export type { ButtonProps } from './Button/Button';
+export type { ButtonLinkProps } from './ButtonLink/ButtonLink';
 export type { CardProps } from './Card/Card';
 export type { ChipProps } from './chip/Chip';
 export type { ContainerProps } from './container/Container';
@@ -34,6 +37,7 @@ export type { HintProps } from './Hint/Hint';
 export type { NotificationBannerProps } from './NotificationBanner/NotificationBanner';
 export type { ExternalLinkProps } from './link/ExternalLink';
 export type { LinkProps } from './link/Link';
+export type { LinkButtonProps } from './LinkButton/LinkButton';
 export type { ParagraphProps } from './Paragraph/Paragraph';
 export type { SlidingPanelProps } from './SlidingPanel/SlidingPanel';
 export type { SkipLinkProps } from './skipLink/SkipLink';
@@ -46,22 +50,15 @@ export { useDropdownMenu } from './dropdown/useDropdownMenu';
 export { SlidingPanel } from './SlidingPanel/SlidingPanel';
 export { Accordion } from './accordion/Accordion';
 export { Modal } from './Modal/Modal';
-export {
-  InfoBox,
-  POSITION_TOP_LEFT,
-  POSITION_TOP_RIGHT,
-  POSITION_BOTTOM_LEFT,
-  POSITION_BOTTOM_RIGHT,
-} from './InfoBox/InfoBox';
 export { ErrorBoundary } from './ErrorBoundary/ErrorBoundary';
 export { ErrorFallback } from './ErrorBoundary/ErrorFallback';
 // NOTE: Select components moved to separate entry point '@tpzdsp/next-toolkit/components/select'
 // export { Select } from './select/Select';
 // export { SelectSkeleton } from './select/SelectSkeleton';
+// NOTE: InfoBox moved to separate entry point '@tpzdsp/next-toolkit/components/info-box'
 
 // Export client component types
 export type { AccordionProps } from './accordion/Accordion';
-export type { InfoBoxProps, Position } from './InfoBox/InfoBox';
 export type { ItemRendererProps } from './dropdown/useDropdownMenu';
 export type { DropdownMenuItem } from './dropdown/DropdownMenu';
 

package/src/components/link/ExternalLink.test.tsx

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+
+import { render, screen } from '@testing-library/react';
+
+import { ExternalLink } from './ExternalLink';
+
+describe('ExternalLink', () => {
+  it('renders with children', () => {
+    render(<ExternalLink href="https://example.com">Visit Example</ExternalLink>);
+
+    const link = screen.getByRole('link', { name: /Visit Example/i });
+
+    expect(link).toBeInTheDocument();
+  });
+
+  it('sets target="_blank" to open in new tab', () => {
+    render(<ExternalLink href="https://example.com">External Link</ExternalLink>);
+
+    const link = screen.getByRole('link');
+
+    expect(link).toHaveAttribute('target', '_blank');
+  });
+
+  it('sets rel="noopener noreferrer" for security', () => {
+    render(<ExternalLink href="https://example.com">External Link</ExternalLink>);
+
+    const link = screen.getByRole('link');
+
+    expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+  });
+
+  it('includes screen reader text indicating new tab', () => {
+    render(<ExternalLink href="https://example.com">Visit Site</ExternalLink>);
+
+    // The accessible name should include the "(opens in new tab)" text
+    const link = screen.getByRole('link', { name: /Visit Site\(opens in new tab\)/i });
+
+    expect(link).toBeInTheDocument();
+  });
+
+  it('applies custom className', () => {
+    render(
+      <ExternalLink href="https://example.com" className="custom-class">
+        Link
+      </ExternalLink>,
+    );
+
+    const link = screen.getByRole('link');
+
+    expect(link).toHaveClass('custom-class');
+  });
+
+  it('preserves default link styling classes', () => {
+    render(<ExternalLink href="https://example.com">Link</ExternalLink>);
+
+    const link = screen.getByRole('link');
+
+    expect(link).toHaveClass('text-link');
+    expect(link).toHaveClass('underline');
+  });
+
+  it('applies href attribute correctly', () => {
+    render(<ExternalLink href="https://example.com">Link</ExternalLink>);
+
+    const link = screen.getByRole('link');
+
+    expect(link).toHaveAttribute('href', 'https://example.com');
+  });
+
+  it('forwards additional props to anchor element', () => {
+    render(
+      <ExternalLink href="https://example.com" data-testid="external-link">
+        Link
+      </ExternalLink>,
+    );
+
+    const link = screen.getByTestId('external-link');
+
+    expect(link).toBeInTheDocument();
+  });
+
+  it('renders with complex children', () => {
+    render(
+      <ExternalLink href="https://example.com">
+        <span>Complex </span>
+
+        <strong>Content</strong>
+      </ExternalLink>,
+    );
+
+    const link = screen.getByRole('link');
+
+    expect(link).toBeInTheDocument();
+    expect(link).toHaveTextContent('Complex Content');
+  });
+
+  it('screen reader text is visually hidden but accessible', () => {
+    render(<ExternalLink href="https://example.com">Link</ExternalLink>);
+
+    const srText = screen.getByText('(opens in new tab)', { exact: false });
+
+    expect(srText).toHaveClass('sr-only');
+  });
+});