@tpzdsp/next-toolkit 1.13.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpzdsp/next-toolkit",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "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",
@@ -200,6 +205,7 @@
   },
   "peerDependencies": {
     "@better-fetch/fetch": "^1.1.21",
+    "@floating-ui/react": "^0.27.17",
     "@tanstack/react-query": "^5.90.19",
     "@testing-library/react": "^16.0.0",
     "@testing-library/user-event": "^14.6.1",
@@ -227,6 +233,9 @@
     "@better-fetch/fetch": {
       "optional": true
     },
+    "@floating-ui/react": {
+      "optional": true
+    },
     "@turf/turf": {
       "optional": true
     },
@@ -272,5 +281,8 @@
   },
   "release": {
     "extends": "./release.config.js"
+  },
+  "dependencies": {
+    "@floating-ui/react": "^0.27.17"
   }
 }

package/src/components/ButtonLink/ButtonLink.stories.tsx

@@ -0,0 +1,72 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { ButtonLink } from './ButtonLink';
+
+const meta = {
+  title: 'Components/ButtonLink',
+  component: ButtonLink,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    type: {
+      control: 'select',
+      options: ['button', 'submit', 'reset'],
+    },
+  },
+} satisfies Meta<typeof ButtonLink>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    children: 'Click me',
+    type: 'button',
+  },
+};
+
+export const WithClickHandler: Story = {
+  args: {
+    children: 'Show alert',
+    onClick: () => alert('Button clicked!'),
+  },
+};
+
+export const Submit: Story = {
+  args: {
+    children: 'Submit form',
+    type: 'submit',
+  },
+  render: (args) => (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        alert('Form submitted!');
+      }}
+    >
+      <ButtonLink {...args} />
+    </form>
+  ),
+};
+
+export const Disabled: Story = {
+  args: {
+    children: 'Disabled button link',
+    disabled: true,
+  },
+};
+
+export const WithCustomStyling: Story = {
+  args: {
+    children: 'Custom styled',
+    className: 'font-bold text-xl',
+  },
+};
+
+export const LongText: Story = {
+  args: {
+    children: 'This is a longer button link that demonstrates how text wraps',
+  },
+};

package/src/components/ButtonLink/ButtonLink.test.tsx

@@ -0,0 +1,154 @@
+import { ButtonLink } from './ButtonLink';
+import { render, screen, userEvent } from '../../test/renderers';
+
+describe('ButtonLink', () => {
+  describe('rendering', () => {
+    it('should render with children', () => {
+      render(<ButtonLink>Click me</ButtonLink>);
+
+      expect(screen.getByRole('button', { name: 'Click me' })).toBeInTheDocument();
+    });
+
+    it('should render as a button element', () => {
+      render(<ButtonLink>Button</ButtonLink>);
+
+      const button = screen.getByRole('button');
+
+      expect(button.tagName).toBe('BUTTON');
+    });
+
+    it('should have link styling classes', () => {
+      render(<ButtonLink>Button</ButtonLink>);
+
+      const button = screen.getByRole('button');
+
+      expect(button).toHaveClass('text-link', 'underline', 'cursor-pointer');
+    });
+
+    it('should merge custom className', () => {
+      render(<ButtonLink className="custom-class">Button</ButtonLink>);
+
+      const button = screen.getByRole('button');
+
+      expect(button).toHaveClass('custom-class');
+      expect(button).toHaveClass('text-link'); // Still has base classes
+    });
+  });
+
+  describe('button types', () => {
+    it('should default to type="button"', () => {
+      render(<ButtonLink>Button</ButtonLink>);
+
+      const button = screen.getByRole('button');
+
+      expect(button).toHaveAttribute('type', 'button');
+    });
+
+    it('should accept type="submit"', () => {
+      render(<ButtonLink type="submit">Submit</ButtonLink>);
+
+      const button = screen.getByRole('button');
+
+      expect(button).toHaveAttribute('type', 'submit');
+    });
+
+    it('should accept type="reset"', () => {
+      render(<ButtonLink type="reset">Reset</ButtonLink>);
+
+      const button = screen.getByRole('button');
+
+      expect(button).toHaveAttribute('type', 'reset');
+    });
+  });
+
+  describe('interactions', () => {
+    it('should handle click events', async () => {
+      const user = userEvent.setup();
+      const onClick = vi.fn();
+
+      render(<ButtonLink onClick={onClick}>Click me</ButtonLink>);
+
+      await user.click(screen.getByRole('button'));
+
+      expect(onClick).toHaveBeenCalledTimes(1);
+    });
+
+    it('should not trigger onClick when disabled', async () => {
+      const user = userEvent.setup();
+      const onClick = vi.fn();
+
+      render(
+        <ButtonLink onClick={onClick} disabled>
+          Disabled
+        </ButtonLink>,
+      );
+
+      await user.click(screen.getByRole('button'));
+
+      expect(onClick).not.toHaveBeenCalled();
+    });
+
+    it('should submit form when type="submit"', () => {
+      const onSubmit = vi.fn((e) => e.preventDefault());
+
+      render(
+        <form onSubmit={onSubmit}>
+          <ButtonLink type="submit">Submit</ButtonLink>
+        </form>,
+      );
+
+      const button = screen.getByRole('button');
+
+      button.click();
+
+      expect(onSubmit).toHaveBeenCalled();
+    });
+  });
+
+  describe('disabled state', () => {
+    it('should have disabled attribute when disabled', () => {
+      render(<ButtonLink disabled>Disabled</ButtonLink>);
+
+      const button = screen.getByRole('button');
+
+      expect(button).toBeDisabled();
+    });
+
+    it('should have reduced opacity when disabled', () => {
+      render(<ButtonLink disabled>Disabled</ButtonLink>);
+
+      const button = screen.getByRole('button');
+
+      expect(button).toHaveClass('disabled:opacity-50');
+    });
+
+    it('should have not-allowed cursor when disabled', () => {
+      render(<ButtonLink disabled>Disabled</ButtonLink>);
+
+      const button = screen.getByRole('button');
+
+      expect(button).toHaveClass('disabled:cursor-not-allowed');
+    });
+  });
+
+  describe('accessibility', () => {
+    it('should have button role', () => {
+      render(<ButtonLink>Button</ButtonLink>);
+
+      expect(screen.getByRole('button')).toBeInTheDocument();
+    });
+
+    it('should accept aria attributes', () => {
+      render(
+        <ButtonLink aria-label="Custom label" aria-describedby="description">
+          Button
+        </ButtonLink>,
+      );
+
+      const button = screen.getByRole('button', { name: 'Custom label' });
+
+      expect(button).toBeInTheDocument();
+      expect(button).toHaveAttribute('aria-describedby', 'description');
+    });
+  });
+});

package/src/components/ButtonLink/ButtonLink.tsx

@@ -0,0 +1,33 @@
+import type { ExtendProps } from '../../types/utils';
+import { cn } from '../../utils';
+
+type Props = {
+  type?: 'submit' | 'reset' | 'button';
+  children: React.ReactNode;
+};
+
+export type ButtonLinkProps = ExtendProps<'button', Props>;
+
+/**
+ * A button that looks like a link.
+ * Use when you need button functionality (onClick, form submission)
+ * but want the visual appearance of a link.
+ */
+export const ButtonLink = ({ type = 'button', className, children, ...props }: ButtonLinkProps) => {
+  return (
+    <button
+      type={type}
+      className={cn(
+        `cursor-pointer text-link hover:decoration-[max(3px,_.1875rem,_.12em)] hover:text-link-hover
+        visited:text-link-visited active:text-black focus:decoration-[max(3px,_.1875rem,_.12em)]
+        decoration-[max(1px,_.0625rem)] underline-offset-[0.1578em] underline outline-none
+        focus:text-focus-text focus:bg-focus inline-block bg-transparent border-0 p-0
+        disabled:opacity-50 disabled:cursor-not-allowed`,
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+};

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

@@ -1,12 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
-import {
-  InfoBox,
-  POSITION_TOP_LEFT,
-  POSITION_TOP_RIGHT,
-  POSITION_BOTTOM_LEFT,
-  POSITION_BOTTOM_RIGHT,
-} from './InfoBox';
+import { InfoBox } from './InfoBox';
 
 const meta = {
   title: 'Components/InfoBox',
@@ -16,7 +10,7 @@ const meta = {
     docs: {
       description: {
         component:
-          'An accessible info box component that displays contextual information in a popover triggered by an info icon button. Auto-positions based on viewport proximity.',
+          '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.',
       },
     },
   },
@@ -39,16 +33,24 @@ const meta = {
       control: 'text',
       description: 'Accessible label for the trigger button',
     },
-    position: {
+    placement: {
       control: 'select',
       options: [
-        undefined,
-        POSITION_TOP_LEFT,
-        POSITION_TOP_RIGHT,
-        POSITION_BOTTOM_LEFT,
-        POSITION_BOTTOM_RIGHT,
+        'top',
+        'top-start',
+        'top-end',
+        'bottom',
+        'bottom-start',
+        'bottom-end',
+        'left',
+        'left-start',
+        'left-end',
+        'right',
+        'right-start',
+        'right-end',
       ],
-      description: 'Force a specific position instead of auto-calculating',
+      description:
+        'Preferred placement (Floating UI will auto-adjust if there is not enough space)',
     },
     children: {
       control: false,
@@ -163,7 +165,8 @@ export const AllPositions: Story = {
     layout: 'fullscreen',
     docs: {
       description: {
-        story: 'Demonstrates all four forced position options for the info box.',
+        story:
+          'Demonstrates various placement options using Floating UI. The content will automatically adjust if there is not enough space.',
       },
     },
   },
@@ -171,40 +174,40 @@ export const AllPositions: Story = {
     <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-right:</span>
+          <span className="text-sm text-gray-600">bottom-start:</span>
 
-          <InfoBox title="Position Demo" position="bottom-right">
-            <p>Opens to the bottom-right of the trigger.</p>
+          <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-left:</span>
+          <span className="text-sm text-gray-600">bottom-end:</span>
 
-          <InfoBox title="Position Demo" position="bottom-left">
-            <p>Opens to the bottom-left of the trigger.</p>
+          <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-right:</span>
+          <span className="text-sm text-gray-600">top-start:</span>
 
-          <InfoBox title="Position Demo" position="top-right">
-            <p>Opens to the top-right of the trigger.</p>
+          <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-left:</span>
+          <span className="text-sm text-gray-600">top-end:</span>
 
-          <InfoBox title="Position Demo" position="top-left">
-            <p>Opens to the top-left of the trigger.</p>
+          <InfoBox title="Position Demo" placement="top-end">
+            <p>Prefers top-end placement.</p>
           </InfoBox>
         </div>
       </div>

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

@@ -1,17 +1,10 @@
-import { InfoBox, POSITION_TOP_LEFT, POSITION_BOTTOM_RIGHT } from './InfoBox';
+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';
 
-// 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', () => {
@@ -131,27 +124,6 @@ describe('InfoBox', () => {
       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>
@@ -164,7 +136,7 @@ describe('InfoBox', () => {
       expect(button).toHaveAttribute('aria-haspopup', 'dialog');
     });
 
-    it('should render as a dialog element', async () => {
+    it('should have dialog role', async () => {
       const user = userEvent.setup();
 
       render(
@@ -177,8 +149,8 @@ describe('InfoBox', () => {
 
       const dialog = screen.getByRole('dialog');
 
-      // Native <dialog> element provides implicit dialog semantics
-      expect(dialog.tagName).toBe('DIALOG');
+      // Floating UI uses div with role="dialog"
+      expect(dialog).toBeInTheDocument();
     });
 
     it('should have aria-labelledby when title is provided', async () => {
@@ -267,34 +239,11 @@ describe('InfoBox', () => {
   });
 
   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 () => {
+    it('should accept placement prop', async () => {
       const user = userEvent.setup();
 
       render(
-        <InfoBox position={POSITION_BOTTOM_RIGHT}>
+        <InfoBox placement="top-start">
           <p>{TEST_CONTENT}</p>
         </InfoBox>,
       );
@@ -303,9 +252,8 @@ describe('InfoBox', () => {
 
       const dialog = screen.getByRole('dialog');
 
-      // bottom-right has no transforms
-      expect(dialog).not.toHaveClass('-translate-x-full');
-      expect(dialog).not.toHaveClass('-translate-y-full');
+      // Floating UI handles positioning automatically
+      expect(dialog).toBeInTheDocument();
     });
   });