@tpzdsp/next-toolkit 1.12.1 → 1.13.0

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

@@ -0,0 +1,382 @@
+import { InfoBox, POSITION_TOP_LEFT, POSITION_BOTTOM_RIGHT } 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';
+
+// Mock focus-trap-react to simplify testing
+vi.mock('focus-trap-react', () => ({
+  FocusTrap: ({ children }: { children: React.ReactNode }) => (
+    <div data-testid="focus-trap">{children}</div>
+  ),
+}));
+
+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-controls linking trigger to content', async () => {
+      const user = userEvent.setup();
+
+      render(
+        <InfoBox>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      const button = screen.getByRole('button', { name: /show information/i });
+      const controlsId = button.getAttribute('aria-controls');
+
+      expect(controlsId).toBeTruthy();
+
+      await user.click(button);
+
+      const dialog = screen.getByRole('dialog');
+
+      expect(dialog).toHaveAttribute('id', controlsId);
+    });
+
+    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 render as a dialog element', 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');
+
+      // Native <dialog> element provides implicit dialog semantics
+      expect(dialog.tagName).toBe('DIALOG');
+    });
+
+    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', () => {
+    beforeEach(() => {
+      // Mock window dimensions
+      Object.defineProperty(globalThis, 'innerWidth', { value: 1000, writable: true });
+      Object.defineProperty(globalThis, 'innerHeight', { value: 800, writable: true });
+    });
+
+    it('should use forced position when position prop is provided', async () => {
+      const user = userEvent.setup();
+
+      render(
+        <InfoBox position={POSITION_TOP_LEFT}>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      await user.click(screen.getByRole('button', { name: /show information/i }));
+
+      const dialog = screen.getByRole('dialog');
+
+      // top-left position applies both X and Y transforms
+      expect(dialog).toHaveClass('-translate-x-full', '-translate-y-full');
+    });
+
+    it('should apply correct transform for bottom-right position', async () => {
+      const user = userEvent.setup();
+
+      render(
+        <InfoBox position={POSITION_BOTTOM_RIGHT}>
+          <p>{TEST_CONTENT}</p>
+        </InfoBox>,
+      );
+
+      await user.click(screen.getByRole('button', { name: /show information/i }));
+
+      const dialog = screen.getByRole('dialog');
+
+      // bottom-right has no transforms
+      expect(dialog).not.toHaveClass('-translate-x-full');
+      expect(dialog).not.toHaveClass('-translate-y-full');
+    });
+  });
+
+  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,177 @@
+'use client';
+
+import { type ReactNode, useRef, useId, type RefObject } 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 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;
+  /** 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;
+  /** Force a specific position instead of auto-calculating */
+  position?: Position;
+};
+
+export type InfoBoxProps = ExtendProps<'div', Props>;
+
+export const InfoBox = ({
+  title,
+  children,
+  defaultOpen = false,
+  onOpenChange,
+  maxWidth = '320px',
+  triggerLabel = 'Show information',
+  position: forcedPosition,
+  className,
+  ...props
+}: InfoBoxProps) => {
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const contentRef = useRef<HTMLDialogElement>(null);
+
+  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',
+    '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(
+    // 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',
+  );
+
+  return (
+    <div className={cn('relative inline-flex', className)} {...props}>
+      <button
+        ref={triggerRef}
+        id={triggerId}
+        type="button"
+        aria-expanded={isOpen}
+        aria-controls={contentId}
+        aria-haspopup="dialog"
+        aria-label={triggerLabel}
+        onClick={toggleOpen}
+        className={triggerClasses}
+      >
+        <FaInfoCircle className={iconClasses} aria-hidden="true" />
+      </button>
+
+      {isMounted &&
+        isOpen &&
+        createPortal(
+          <FocusTrap active={isTrapActive} focusTrapOptions={focusTrapConfig}>
+            <dialog
+              ref={contentRef}
+              id={contentId}
+              open
+              aria-labelledby={title ? titleId : undefined}
+              aria-label={title ? undefined : 'Information'}
+              tabIndex={-1}
+              style={{
+                top: contentPosition.top,
+                left: contentPosition.left,
+                maxWidth: `min(${maxWidth}, calc(100vw - 32px))`,
+              }}
+              className={contentClasses}
+            >
+              {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>
+            </dialog>
+          </FocusTrap>,
+          document.body,
+        )}
+    </div>
+  );
+};

package/src/components/InfoBox/hooks/index.ts

@@ -0,0 +1,3 @@
+export { useInfoBoxPosition } from './useInfoBoxPosition';
+export { useInfoBoxState } from './useInfoBoxState';
+export { usePortalMount } from './usePortalMount';