@tpzdsp/next-toolkit 1.12.3 → 1.12.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpzdsp/next-toolkit",
-  "version": "1.12.3",
+  "version": "1.12.5",
   "description": "A reusable React component library for Next.js applications",
   "engines": {
     "node": ">= 24.12.0",
@@ -57,6 +57,11 @@
       "import": "./src/components/select/index.ts",
       "require": "./src/components/select/index.ts"
     },
+    "./components/info-box": {
+      "types": "./src/components/InfoBox/InfoBox.tsx",
+      "import": "./src/components/InfoBox/InfoBox.tsx",
+      "require": "./src/components/InfoBox/InfoBox.tsx"
+    },
     "./http": {
       "types": "./src/http/index.ts",
       "import": "./src/http/index.ts",
@@ -119,6 +124,7 @@
   },
   "devDependencies": {
     "@better-fetch/fetch": "^1.1.21",
+    "@floating-ui/react": "^0.27.17",
     "@eslint/js": "^9.30.1",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
@@ -229,6 +235,9 @@
     "@better-fetch/fetch": {
       "optional": true
     },
+    "@floating-ui/react": {
+      "optional": true
+    },
     "@turf/turf": {
       "optional": true
     },

package/src/components/InfoBox/InfoBox.stories.tsx

@@ -0,0 +1,460 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { InfoBox } from './InfoBox';
+
+const meta = {
+  title: 'Components/InfoBox',
+  component: InfoBox,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'An accessible info box component that displays contextual information in a popover triggered by an info icon button. Uses Floating UI for intelligent auto-positioning that adapts to viewport constraints.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    title: {
+      control: 'text',
+      description: 'Optional title displayed at the top of the info box content',
+    },
+    defaultOpen: {
+      control: 'boolean',
+      description: 'Whether the info box starts open',
+      defaultValue: false,
+    },
+    maxWidth: {
+      control: 'text',
+      description: 'Maximum width of the content box (default: 320px)',
+    },
+    triggerLabel: {
+      control: 'text',
+      description: 'Accessible label for the trigger button',
+    },
+    placement: {
+      control: 'select',
+      options: [
+        'top',
+        'top-start',
+        'top-end',
+        'bottom',
+        'bottom-start',
+        'bottom-end',
+        'left',
+        'left-start',
+        'left-end',
+        'right',
+        'right-start',
+        'right-end',
+      ],
+      description:
+        'Preferred placement (Floating UI will auto-adjust if there is not enough space)',
+    },
+    children: {
+      control: false,
+      description: 'Content to display inside the info box',
+    },
+    onOpenChange: {
+      action: 'onOpenChange',
+      description: 'Callback when the info box opens or closes',
+    },
+  },
+} satisfies Meta<typeof InfoBox>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    children: <p>This is helpful information about this feature.</p>,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Basic info box with simple text content. Click the info icon to open.',
+      },
+    },
+  },
+};
+
+export const WithTitle: Story = {
+  args: {
+    title: 'Important Information',
+    children: (
+      <div className="space-y-2">
+        <p>Here are some key points to remember:</p>
+
+        <ul className="list-disc list-inside text-sm">
+          <li>Point one</li>
+
+          <li>Point two</li>
+
+          <li>Point three</li>
+        </ul>
+      </div>
+    ),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Info box with a title header for more structured content.',
+      },
+    },
+  },
+};
+
+export const DefaultOpen: Story = {
+  args: {
+    title: 'Getting Started',
+    defaultOpen: true,
+    children: <p>This info box starts open by default.</p>,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Info box that starts in the open state.',
+      },
+    },
+  },
+};
+
+export const LongContent: Story = {
+  args: {
+    title: 'Detailed Information',
+    maxWidth: '400px',
+    children: (
+      <div className="space-y-2 max-h-48 overflow-y-auto">
+        <p>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt
+          ut labore et dolore magna aliqua.
+        </p>
+
+        <p>
+          Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
+          commodo consequat.
+        </p>
+
+        <p>
+          Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat
+          nulla pariatur.
+        </p>
+
+        <p>
+          Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit
+          anim id est laborum.
+        </p>
+      </div>
+    ),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Info box with longer scrollable content and custom max width.',
+      },
+    },
+  },
+};
+
+export const AllPositions: Story = {
+  args: {
+    children: null,
+  },
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        story:
+          'Demonstrates various placement options using Floating UI. The content will automatically adjust if there is not enough space.',
+      },
+    },
+  },
+  render: () => (
+    <div className="p-8 grid grid-cols-2 gap-8 h-screen">
+      <div className="flex items-start justify-start">
+        <div className="flex items-center gap-2">
+          <span className="text-sm text-gray-600">bottom-start:</span>
+
+          <InfoBox title="Position Demo" placement="bottom-start">
+            <p>Prefers bottom-start placement.</p>
+          </InfoBox>
+        </div>
+      </div>
+
+      <div className="flex items-start justify-end">
+        <div className="flex items-center gap-2">
+          <span className="text-sm text-gray-600">bottom-end:</span>
+
+          <InfoBox title="Position Demo" placement="bottom-end">
+            <p>Prefers bottom-end placement.</p>
+          </InfoBox>
+        </div>
+      </div>
+
+      <div className="flex items-end justify-start">
+        <div className="flex items-center gap-2">
+          <span className="text-sm text-gray-600">top-start:</span>
+
+          <InfoBox title="Position Demo" placement="top-start">
+            <p>Prefers top-start placement.</p>
+          </InfoBox>
+        </div>
+      </div>
+
+      <div className="flex items-end justify-end">
+        <div className="flex items-center gap-2">
+          <span className="text-sm text-gray-600">top-end:</span>
+
+          <InfoBox title="Position Demo" placement="top-end">
+            <p>Prefers top-end placement.</p>
+          </InfoBox>
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+export const InCorners: Story = {
+  args: {
+    children: null,
+  },
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        story:
+          'Demonstrates auto-positioning when the info box is placed in different corners of the viewport. The info box automatically positions itself to stay visible.',
+      },
+    },
+  },
+  render: () => (
+    <div className="relative h-screen w-full">
+      <div className="absolute top-4 left-4 flex items-center gap-2">
+        <InfoBox>
+          <p>Auto-positioned from top-left corner. Should open to bottom-right.</p>
+        </InfoBox>
+
+        <span className="text-xs text-gray-500">Top-left corner</span>
+      </div>
+
+      <div className="absolute top-4 right-4 flex items-center gap-2">
+        <span className="text-xs text-gray-500">Top-right corner</span>
+
+        <InfoBox>
+          <p>Auto-positioned from top-right corner. Should open to bottom-left.</p>
+        </InfoBox>
+      </div>
+
+      <div className="absolute bottom-4 left-4 flex items-center gap-2">
+        <InfoBox>
+          <p>Auto-positioned from bottom-left corner. Should open to top-right.</p>
+        </InfoBox>
+
+        <span className="text-xs text-gray-500">Bottom-left corner</span>
+      </div>
+
+      <div className="absolute bottom-4 right-4 flex items-center gap-2">
+        <span className="text-xs text-gray-500">Bottom-right corner</span>
+
+        <InfoBox>
+          <p>Auto-positioned from bottom-right corner. Should open to top-left.</p>
+        </InfoBox>
+      </div>
+
+      <div className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 text-center">
+        <p className="text-gray-400 text-sm">
+          Click the info icons in each corner to see auto-positioning
+        </p>
+      </div>
+    </div>
+  ),
+};
+
+export const WithInteractiveContent: Story = {
+  args: {
+    title: 'Take Action',
+    children: (
+      <div className="space-y-3">
+        <p className="text-sm">You can interact with elements inside:</p>
+
+        <input
+          type="text"
+          placeholder="Type something..."
+          className="w-full px-3 py-2 text-sm border border-gray-300 rounded focus:outline-none
+            focus:ring-2 focus:ring-blue-500"
+        />
+
+        <button
+          type="button"
+          className="w-full px-4 py-2 text-sm text-white bg-blue-600 rounded hover:bg-blue-700
+            focus:outline-none focus:ring-2 focus:ring-blue-500"
+        >
+          Submit
+        </button>
+      </div>
+    ),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Info box with interactive content (form elements). Focus is trapped within the info box when open.',
+      },
+    },
+  },
+};
+
+export const InlineWithText: Story = {
+  args: {
+    children: null,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Info box used inline with paragraph text to provide contextual information.',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-md p-4">
+      <p className="text-sm leading-relaxed">
+        This is a paragraph with an inline info box{' '}
+        <span className="inline-flex align-middle mx-1">
+          <InfoBox triggerLabel="Learn more about this term">
+            <p>Additional context about the preceding text that helps explain the concept.</p>
+          </InfoBox>
+        </span>{' '}
+        that provides more context about a specific term or concept in the text.
+      </p>
+    </div>
+  ),
+};
+
+export const CustomTriggerLabel: Story = {
+  args: {
+    triggerLabel: 'Learn more about data privacy',
+    title: 'Data Privacy',
+    children: (
+      <div className="space-y-2 text-sm">
+        <p>Your data is handled securely and in accordance with our privacy policy.</p>
+
+        <a href="https://example.com" className="text-blue-600 hover:underline">
+          Read our full privacy policy
+        </a>
+      </div>
+    ),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Info box with a custom trigger label for better accessibility context. Screen readers will announce the custom label.',
+      },
+    },
+  },
+};
+
+export const MultipleInfoBoxes: Story = {
+  args: {
+    children: null,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Multiple info boxes can be used independently on the same page.',
+      },
+    },
+  },
+  render: () => (
+    <div className="space-y-4 p-4">
+      <div className="flex items-center gap-2">
+        <span className="text-sm font-medium">Username</span>
+
+        <InfoBox triggerLabel="Username requirements">
+          <p className="text-sm">Username must be 3-20 characters and contain only letters.</p>
+        </InfoBox>
+      </div>
+
+      <div className="flex items-center gap-2">
+        <span className="text-sm font-medium">Password</span>
+
+        <InfoBox triggerLabel="Password requirements">
+          <div className="text-sm space-y-1">
+            <p>Password must contain:</p>
+
+            <ul className="list-disc list-inside">
+              <li>At least 8 characters</li>
+
+              <li>One uppercase letter</li>
+
+              <li>One number</li>
+            </ul>
+          </div>
+        </InfoBox>
+      </div>
+
+      <div className="flex items-center gap-2">
+        <span className="text-sm font-medium">Email</span>
+
+        <InfoBox triggerLabel="Why we need your email">
+          <p className="text-sm">We use your email for account recovery and important updates.</p>
+        </InfoBox>
+      </div>
+    </div>
+  ),
+};
+
+export const Accessibility: Story = {
+  args: {
+    children: null,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Demonstrates the accessibility features of the InfoBox component.',
+      },
+    },
+  },
+  render: () => (
+    <div className="space-y-6 max-w-md p-4">
+      <div className="bg-blue-50 border border-blue-200 rounded p-4">
+        <h3 className="font-bold text-blue-800 mb-2">Accessibility Features:</h3>
+
+        <ul className="list-disc list-inside space-y-1 text-blue-700 text-sm">
+          <li>Trigger button has aria-expanded and aria-haspopup</li>
+
+          <li>Content has role=&quot;dialog&quot; and aria-modal=&quot;true&quot;</li>
+
+          <li>Focus is trapped within the info box when open</li>
+
+          <li>Escape key closes the info box</li>
+
+          <li>Click outside closes the info box</li>
+
+          <li>Focus returns to trigger on close (via keyboard)</li>
+
+          <li>Title provides aria-labelledby relationship</li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-2">
+        <span className="text-sm">Try this accessible info box:</span>
+
+        <InfoBox title="Accessible Info Box" triggerLabel="Show accessibility information">
+          <div className="text-sm space-y-2">
+            <p>This info box demonstrates proper accessibility:</p>
+
+            <ul className="list-disc list-inside">
+              <li>Use Tab to navigate between elements</li>
+
+              <li>Press Escape to close</li>
+
+              <li>Click outside to close</li>
+            </ul>
+          </div>
+        </InfoBox>
+      </div>
+    </div>
+  ),
+};

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,172 @@
+'use client';
+
+import { type ReactNode, type ComponentType, 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;
+  /** Custom icon component to replace the default FaInfoCircle */
+  icon?: ComponentType<{ className?: string }>;
+};
+
+export type InfoBoxProps = ExtendProps<'div', Props>;
+
+export const InfoBox = ({
+  title,
+  children,
+  defaultOpen = false,
+  onOpenChange,
+  maxWidth = '320px',
+  triggerLabel = 'Show information',
+  placement = 'bottom-start',
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  icon: Icon = FaInfoCircle,
+  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, auto when closed
+    isOpen ? 'text-focus' : '',
+    // 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()}
+      >
+        <Icon 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/index.ts

@@ -51,6 +51,7 @@ 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';

package/src/map/MapComponent.tsx

@@ -89,12 +89,8 @@ export const MapComponent = ({
     const attribution = new Attribution();
     const layerSwitcher = new LayerSwitcherControl(layers);
 
-    // Add controls in the desired order
-    const controls = [mapZoom, layerSwitcher, scaleLine, attribution];
-
     const newMap = new Map({
       target,
-      controls,
       layers,
       view: new View({
         projection: 'EPSG:3857',
@@ -108,12 +104,7 @@ export const MapComponent = ({
       }),
     });
 
-    // Mark the map as initialized to prevent re-initialization
-    // This is a workaround to avoid re-initializing the map when the component
-    // re-renders. The map is only initialized once when the component mounts.
-    // This is important because the map is a singleton and should not be
-    // re-initialized.
-    mapInitializedRef.current = true;
+    const controls = [mapZoom, layerSwitcher, scaleLine, attribution];
 
     // Create an instance of the custom provider, passing any options that are
     // required
@@ -122,12 +113,23 @@ export const MapComponent = ({
       try {
         const geocoder = initializeGeocoder(osMapsApiKey, geocoderUrl, newMap);
 
-        newMap.addControl(geocoder as Control);
+        // Put geocoder first so the tabbing order is sensible
+        controls.unshift(geocoder);
       } catch (error) {
         console.error('Failed to initialize geocoder:', error);
       }
     }
 
+    // Add controls in the desired order
+    controls.forEach((control) => newMap.addControl(control));
+
+    // Mark the map as initialized to prevent re-initialization
+    // This is a workaround to avoid re-initializing the map when the component
+    // re-renders. The map is only initialized once when the component mounts.
+    // This is important because the map is a singleton and should not be
+    // re-initialized.
+    mapInitializedRef.current = true;
+
     // Setup popup overlay
     const overlay = new Overlay({
       element: document.getElementById('popup-container') ?? undefined,