@tpzdsp/next-toolkit 1.12.1 → 1.14.0

package/src/components/InfoBox/InfoBox.test.tsx

@@ -0,0 +1,330 @@
+import { InfoBox } from './InfoBox';
+import { render, screen, userEvent, waitFor } from '../../test/renderers';
+
+const TEST_CONTENT = 'Test info content';
+const TEST_TITLE = 'Test Title';
+const ARIA_EXPANDED = 'aria-expanded';
+
+describe('InfoBox', () => {
+  describe('rendering', () => {
+    it('should render the trigger button with info icon', () => {
+      render(
+        <InfoBox>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      const button = screen.getByRole('button', { name: /show information/i });
+
+      expect(button).toBeInTheDocument();
+      expect(button.querySelector('svg')).toBeInTheDocument();
+    });
+
+    it('should not render content when closed', () => {
+      render(
+        <InfoBox>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      expect(screen.queryByText(TEST_CONTENT)).not.toBeInTheDocument();
+    });
+
+    it('should render content when defaultOpen is true', () => {
+      render(
+        <InfoBox defaultOpen>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      expect(screen.getByText(TEST_CONTENT)).toBeInTheDocument();
+    });
+
+    it('should render title when provided', () => {
+      render(
+        <InfoBox title={TEST_TITLE} defaultOpen>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      expect(screen.getByText(TEST_TITLE)).toBeInTheDocument();
+      expect(screen.getByRole('heading', { level: 2 })).toHaveTextContent(TEST_TITLE);
+    });
+
+    it('should not render title element when not provided', () => {
+      render(
+        <InfoBox defaultOpen>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      expect(screen.queryByRole('heading')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('interactions', () => {
+    it('should open content when trigger is clicked', async () => {
+      const user = userEvent.setup();
+
+      render(
+        <InfoBox>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      const button = screen.getByRole('button', { name: /show information/i });
+
+      expect(screen.queryByText(TEST_CONTENT)).not.toBeInTheDocument();
+
+      await user.click(button);
+
+      expect(screen.getByText(TEST_CONTENT)).toBeInTheDocument();
+    });
+
+    it('should close content when trigger is clicked while open', async () => {
+      const user = userEvent.setup();
+
+      render(
+        <InfoBox defaultOpen>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      expect(screen.getByText(TEST_CONTENT)).toBeInTheDocument();
+
+      const button = screen.getByRole('button', { name: /show information/i });
+
+      await user.click(button);
+
+      await waitFor(() => {
+        expect(screen.queryByText(TEST_CONTENT)).not.toBeInTheDocument();
+      });
+    });
+
+    // Note: Escape key closing is handled by FocusTrap, which is mocked in tests.
+    // The real behavior is tested through FocusTrap's own test suite.
+  });
+
+  describe('accessibility', () => {
+    it('should have aria-expanded attribute that toggles correctly', async () => {
+      const user = userEvent.setup();
+
+      render(
+        <InfoBox>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      const button = screen.getByRole('button', { name: /show information/i });
+
+      expect(button).toHaveAttribute(ARIA_EXPANDED, 'false');
+
+      await user.click(button);
+
+      expect(button).toHaveAttribute(ARIA_EXPANDED, 'true');
+    });
+
+    it('should have aria-haspopup="dialog" on trigger', () => {
+      render(
+        <InfoBox>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      const button = screen.getByRole('button', { name: /show information/i });
+
+      expect(button).toHaveAttribute('aria-haspopup', 'dialog');
+    });
+
+    it('should have dialog role', async () => {
+      const user = userEvent.setup();
+
+      render(
+        <InfoBox>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      await user.click(screen.getByRole('button', { name: /show information/i }));
+
+      const dialog = screen.getByRole('dialog');
+
+      // Floating UI uses div with role="dialog"
+      expect(dialog).toBeInTheDocument();
+    });
+
+    it('should have aria-labelledby when title is provided', async () => {
+      const user = userEvent.setup();
+
+      render(
+        <InfoBox title={TEST_TITLE}>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      await user.click(screen.getByRole('button', { name: /show information/i }));
+
+      const dialog = screen.getByRole('dialog');
+      const titleId = dialog.getAttribute('aria-labelledby');
+
+      expect(titleId).toBeTruthy();
+
+      const title = screen.getByRole('heading', { level: 2 });
+
+      expect(title).toHaveAttribute('id', titleId);
+    });
+
+    it('should have aria-label when title is not provided', async () => {
+      const user = userEvent.setup();
+
+      render(
+        <InfoBox>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      await user.click(screen.getByRole('button', { name: /show information/i }));
+
+      const dialog = screen.getByRole('dialog');
+
+      expect(dialog).toHaveAttribute('aria-label', 'Information');
+      expect(dialog).not.toHaveAttribute('aria-labelledby');
+    });
+
+    it('should use custom triggerLabel when provided', () => {
+      render(
+        <InfoBox triggerLabel="Learn more about this feature">
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      expect(
+        screen.getByRole('button', { name: /learn more about this feature/i }),
+      ).toBeInTheDocument();
+    });
+  });
+
+  describe('callbacks', () => {
+    it('should call onOpenChange when opening', async () => {
+      const user = userEvent.setup();
+      const onOpenChange = vi.fn();
+
+      render(
+        <InfoBox onOpenChange={onOpenChange}>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      await user.click(screen.getByRole('button', { name: /show information/i }));
+
+      expect(onOpenChange).toHaveBeenCalledWith(true);
+    });
+
+    it('should call onOpenChange when closing', async () => {
+      const user = userEvent.setup();
+      const onOpenChange = vi.fn();
+
+      render(
+        <InfoBox defaultOpen onOpenChange={onOpenChange}>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      await user.click(screen.getByRole('button', { name: /show information/i }));
+
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(false);
+      });
+    });
+  });
+
+  describe('positioning', () => {
+    it('should accept placement prop', async () => {
+      const user = userEvent.setup();
+
+      render(
+        <InfoBox placement="top-start">
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      await user.click(screen.getByRole('button', { name: /show information/i }));
+
+      const dialog = screen.getByRole('dialog');
+
+      // Floating UI handles positioning automatically
+      expect(dialog).toBeInTheDocument();
+    });
+  });
+
+  describe('styling', () => {
+    it('should apply maxWidth style', async () => {
+      const user = userEvent.setup();
+
+      render(
+        <InfoBox maxWidth="400px">
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      await user.click(screen.getByRole('button', { name: /show information/i }));
+
+      const dialog = screen.getByRole('dialog');
+
+      expect(dialog).toHaveStyle({ maxWidth: 'min(400px, calc(100vw - 32px))' });
+    });
+
+    it('should merge custom className', () => {
+      render(
+        <InfoBox className="custom-class">
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      const container = screen.getByRole('button', { name: /show information/i }).parentElement;
+
+      expect(container).toHaveClass('custom-class');
+    });
+
+    it('should have correct trigger button styling', () => {
+      render(
+        <InfoBox>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      const button = screen.getByRole('button', { name: /show information/i });
+
+      expect(button).toHaveClass('rounded-full', 'bg-transparent');
+    });
+  });
+
+  describe('complex content', () => {
+    it('should render interactive content correctly', async () => {
+      const user = userEvent.setup();
+      const onButtonClick = vi.fn();
+
+      render(
+        <InfoBox defaultOpen>
+          <div>
+            <p>Description text</p>
+
+            <input type="text" placeholder="Enter text" />
+
+            <button onClick={onButtonClick}>Action</button>
+          </div>
+        </InfoBox>,
+      );
+
+      expect(screen.getByText('Description text')).toBeInTheDocument();
+      expect(screen.getByPlaceholderText('Enter text')).toBeInTheDocument();
+
+      const actionButton = screen.getByRole('button', { name: 'Action' });
+
+      expect(actionButton).toBeInTheDocument();
+
+      await user.click(actionButton);
+      expect(onButtonClick).toHaveBeenCalled();
+    });
+  });
+});

package/src/components/InfoBox/InfoBox.tsx

@@ -0,0 +1,168 @@
+'use client';
+
+import { type ReactNode, useRef, useId, useState } from 'react';
+
+import { FaInfoCircle } from 'react-icons/fa';
+
+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';
+
+type Props = {
+  /** Optional title displayed at the top of the info box content */
+  title?: string;
+  /** Content to display inside the info box */
+  children: ReactNode;
+  /** Whether the info box starts open (default: false) */
+  defaultOpen?: boolean;
+  /** Callback when the info box opens or closes */
+  onOpenChange?: (isOpen: boolean) => void;
+  /** Maximum width of the info box (default: '320px') */
+  maxWidth?: string;
+  /** Custom aria-label for the trigger button (default: 'Show information') */
+  triggerLabel?: string;
+  /** Preferred placement (Floating UI will auto-adjust if needed) */
+  placement?: Placement;
+};
+
+export type InfoBoxProps = ExtendProps<'div', Props>;
+
+export const InfoBox = ({
+  title,
+  children,
+  defaultOpen = false,
+  onOpenChange,
+  maxWidth = '320px',
+  triggerLabel = 'Show information',
+  placement = 'bottom-start',
+  className,
+  ...props
+}: InfoBoxProps) => {
+  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();
+
+  const triggerClasses = cn(
+    // Base styles - button structure only
+    'inline-flex items-center justify-center',
+    'w-6 h-6 rounded-full',
+    'bg-transparent border-none',
+    // Focus outline only
+    'focus:outline focus:outline-[3px] focus:outline-focus',
+  );
+
+  const iconClasses = cn(
+    // Icon size
+    'w-5 h-5',
+    // Icon color - yellow when open, black when closed
+    isOpen ? 'text-focus' : 'text-black',
+    // Hover state - yellow
+    'hover:text-focus',
+    // Focus state - yellow
+    'focus:text-focus',
+    // Transition
+    'transition-colors duration-150',
+  );
+
+  const contentClasses = cn(
+    // Base styles
+    'bg-white rounded-lg shadow-lg border border-gray-200',
+    'p-4',
+    // Width constraints
+    'min-w-[280px]',
+    // Z-index
+    'z-50',
+  );
+
+  return (
+    <div className={cn('relative inline-flex', className)} {...props}>
+      <button
+        ref={refs.setReference}
+        id={triggerId}
+        type="button"
+        aria-expanded={isOpen}
+        aria-controls={contentId}
+        aria-haspopup="dialog"
+        aria-label={triggerLabel}
+        className={triggerClasses}
+        {...getReferenceProps()}
+      >
+        <FaInfoCircle className={iconClasses} aria-hidden="true" />
+      </button>
+
+      {isOpen && (
+        <FloatingPortal>
+          <FloatingFocusManager context={context} modal={false}>
+            <div
+              ref={refs.setFloating}
+              id={contentId}
+              aria-labelledby={title ? titleId : undefined}
+              aria-label={title ? undefined : 'Information'}
+              style={{
+                ...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}
+                </h2>
+              ) : null}
+              <div
+                className="text-sm text-gray-700 max-h-[min(24rem,calc(100vh-200px))]
+                  overflow-y-auto"
+              >
+                {children}
+              </div>
+            </div>
+          </FloatingFocusManager>
+        </FloatingPortal>
+      )}
+    </div>
+  );
+};

package/src/components/InfoBox/types.ts

@@ -0,0 +1,6 @@
+export type Position = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+export const POSITION_TOP_LEFT: Position = 'top-left';
+export const POSITION_TOP_RIGHT: Position = 'top-right';
+export const POSITION_BOTTOM_LEFT: Position = 'bottom-left';
+export const POSITION_BOTTOM_RIGHT: Position = 'bottom-right';

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',
+  },
+};