@tpzdsp/next-toolkit 1.2.9 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpzdsp/next-toolkit",
-  "version": "1.2.9",
+  "version": "1.3.0",
   "description": "A reusable React component library for Next.js applications",
   "type": "module",
   "private": false,
@@ -111,6 +111,7 @@
     "@storybook/react": "8.6.14",
     "@storybook/react-vite": "8.6.14",
     "@storybook/test": "^8.6.14",
+    "@storybook/types": "8.6.14",
     "@tailwindcss/typography": "^0.5.16",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
@@ -129,6 +130,8 @@
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/eslint-plugin": "^1.3.4",
     "autoprefixer": "^10.4.21",
+    "buffer": "^6.0.3",
+    "crypto-browserify": "^3.12.1",
     "eslint": "^9.30.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-alias": "^1.1.2",
@@ -155,6 +158,7 @@
     "prettier": "^3.6.2",
     "prettier-plugin-classnames": "^0.8.1",
     "prettier-plugin-tailwindcss": "^0.6.14",
+    "process": "^0.11.10",
     "proj4": "^2.19.10",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
@@ -164,10 +168,12 @@
     "rollup-plugin-peer-deps-external": "^2.2.4",
     "semantic-release": "^24.2.7",
     "storybook": "8.6.14",
+    "stream-browserify": "^3.0.0",
     "tailwind-merge": "^3.3.1",
     "tailwindcss": "^3.4.16",
     "typescript": "~5.8.3",
     "typescript-eslint": "^8.35.1",
+    "util": "^0.12.5",
     "vite": "^7.0.4",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^3.2.4"

package/src/components/Card/Card.stories.tsx

@@ -1,7 +1,10 @@
+import { FaChevronRight } from 'react-icons/fa6';
+
 /* eslint-disable storybook/no-renderer-packages */
 import type { Meta, StoryFn } from '@storybook/react';
 
 import { Card, type CardProps } from './Card';
+import { Paragraph } from '../Paragraph/Paragraph';
 
 export default {
   children: 'Card',
@@ -33,3 +36,21 @@ ImageAndText.args = {
     </div>
   ),
 };
+
+export const WithLink = Template.bind({});
+WithLink.args = {
+  children: (
+    <>
+      <a
+        href="https://google.co.uk"
+        className="mb-4 flex flex-nowrap items-center gap-2 justify-between font-bold"
+      >
+        <strong>title</strong>
+
+        <FaChevronRight className="text-base" />
+      </a>
+
+      <Paragraph>Some descriptive text</Paragraph>
+    </>
+  ),
+};

package/src/components/Card/Card.test.tsx

@@ -1,12 +1,51 @@
-import { describe, expect, it } from 'vitest';
-
 import { Card } from './Card';
-import { render, screen } from '../../test/renderers';
+import { render, screen, userEvent, within } from '../../test/renderers';
+
+describe('Card Component', () => {
+  it('renders children correctly', () => {
+    render(
+      <Card>
+        <p>Hello, World!</p>
+      </Card>,
+    );
+
+    expect(within(screen.getByRole('article')).getByText('Hello, World!')).toBeInTheDocument();
+  });
+
+  it('renders a link inside the card and handles click', async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+
+    render(
+      <Card>
+        <a href="/some-path" onClick={handleClick}>
+          Go to page
+        </a>
+      </Card>,
+    );
+
+    const link = screen.getByRole('link', { name: /go to page/i });
+
+    expect(link).toBeInTheDocument();
+
+    await user.click(link);
+    expect(handleClick).toHaveBeenCalled();
+  });
+
+  it('merges custom className correctly', () => {
+    render(<Card className="bg-red-500 rounded-lg">Custom</Card>);
+    const article = screen.getByRole('article');
+
+    expect(article).toHaveClass('bg-red-500');
+    expect(article).toHaveClass('rounded-lg');
+  });
 
-describe('Card', () => {
-  it('renders with default color blue', () => {
-    render(<Card>Some test text</Card>);
+  it('overrides conflicting className using twMerge', () => {
+    render(<Card className="pt-4">Override Padding</Card>);
+    const article = screen.getByRole('article');
 
-    expect(screen.getByRole('article')).toBeInTheDocument();
+    // Should NOT have original 'pt-[12px]' due to twMerge override
+    expect(article?.className).not.toMatch(/pt-\[12px\]/);
+    expect(article).toHaveClass('pt-4');
   });
 });

package/src/components/Card/Card.tsx

@@ -9,7 +9,7 @@ export const Card = ({ className, children }: CardProps) => {
   return (
     <article
       className={twMerge(
-        'relative my-6 flex w-96 flex-col rounded-lg border border-slate-200 bg-white p-2 shadow-sm',
+        'h-full flex flex-col pt-[12px] px-[4px] mx-3 border-t border-slate-500',
         className,
       )}
     >

package/src/components/Paragraph/Paragraph.tsx

@@ -1,7 +1,11 @@
-export type ParagraphProps = {
-  children: React.ReactNode;
-};
+import type { ExtendProps } from '../../types/utils';
+
+export type ParagraphProps = ExtendProps<'p'>;
 
-export const Paragraph = ({ children }: ParagraphProps) => {
-  return <p className="pb-4 text-sm text-text-primary">{children}</p>;
+export const Paragraph = ({ className, children, ...props }: ParagraphProps) => {
+  return (
+    <p className={`pb-4 text-sm text-text-primary ${className}`} {...props}>
+      {children}
+    </p>
+  );
 };

package/src/components/backToTop/BackToTop.stories.tsx

@@ -0,0 +1,409 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+/* eslint-disable storybook/no-renderer-packages */
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { BackToTop } from './BackToTop';
+
+const meta = {
+  title: 'Components/BackToTop',
+  component: BackToTop,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'A floating "Back to Top" button that appears when the user scrolls down and allows quick navigation back to the top of the page.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    threshold: {
+      control: { type: 'number', min: 0, max: 2000, step: 100 },
+      description: 'Scroll threshold in pixels before button appears',
+      defaultValue: 600,
+    },
+    bottom: {
+      control: { type: 'number', min: 0, max: 100, step: 4 },
+      description: 'Position from bottom in pixels',
+      defaultValue: 16,
+    },
+    left: {
+      control: { type: 'number', min: 0, max: 100, step: 4 },
+      description: 'Position from left in pixels',
+      defaultValue: 8,
+    },
+    className: {
+      control: 'text',
+      description: 'Custom className for additional styling',
+    },
+  },
+} satisfies Meta<typeof BackToTop>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Default back to top button. Scroll down to see it appear at 600px threshold.',
+      },
+    },
+  },
+  render: (args) => (
+    <div>
+      <BackToTop {...args} />
+
+      <div className="space-y-8 p-8">
+        <h1 className="text-3xl font-bold">Scroll down to see the Back to Top button</h1>
+
+        <div className="space-y-6">
+          {Array.from({ length: 50 }, (_, i) => (
+            <div key={i} className="p-4 bg-gray-100 rounded">
+              <h2 className="text-xl font-semibold mb-2">Section {i + 1}</h2>
+
+              <p>
+                This is content section {i + 1}. Lorem ipsum dolor sit amet, consectetur adipiscing
+                elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
+                minim veniam, quis nostrud exercitation ullamco laboris.
+              </p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+export const LowThreshold: Story = {
+  args: {
+    threshold: 200,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Back to top button with a low threshold (200px) - appears quickly when scrolling.',
+      },
+    },
+  },
+  render: (args) => (
+    <div>
+      <BackToTop {...args} />
+
+      <div className="space-y-8 p-8">
+        <h1 className="text-3xl font-bold">Low Threshold Example (200px)</h1>
+
+        <div className="bg-yellow-100 border border-yellow-400 rounded p-4 mb-6">
+          <p className="text-yellow-800">
+            This example has a low threshold of 200px. The button will appear much sooner when
+            scrolling.
+          </p>
+        </div>
+
+        <div className="space-y-6">
+          {Array.from({ length: 30 }, (_, i) => (
+            <div key={i} className="p-4 bg-blue-50 rounded">
+              <h2 className="text-xl font-semibold mb-2">Content Block {i + 1}</h2>
+
+              <p>
+                Content with low threshold setting. The back to top button should appear after
+                scrolling just 200 pixels down the page.
+              </p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+export const CustomPosition: Story = {
+  args: {
+    bottom: 32,
+    left: 32,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Back to top button with custom positioning (32px from bottom and left).',
+      },
+    },
+  },
+  render: (args) => (
+    <div>
+      <BackToTop {...args} />
+
+      <div className="space-y-8 p-8">
+        <h1 className="text-3xl font-bold">Custom Position Example</h1>
+
+        <div className="bg-green-100 border border-green-400 rounded p-4 mb-6">
+          <p className="text-green-800">
+            This button is positioned 32px from both bottom and left edges.
+          </p>
+        </div>
+
+        <div className="space-y-6">
+          {Array.from({ length: 40 }, (_, i) => (
+            <div key={i} className="p-4 bg-green-50 rounded">
+              <h2 className="text-xl font-semibold mb-2">Section {i + 1}</h2>
+
+              <p>Scroll down to see the back to top button in its custom position.</p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+export const RightAligned: Story = {
+  args: {
+    left: undefined,
+    className: 'right-4',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Back to top button positioned on the right side using custom className.',
+      },
+    },
+  },
+  render: (args) => (
+    <div>
+      <BackToTop {...args} />
+
+      <div className="space-y-8 p-8">
+        <h1 className="text-3xl font-bold">Right-Aligned Button</h1>
+
+        <div className="bg-purple-100 border border-purple-400 rounded p-4 mb-6">
+          <p className="text-purple-800">
+            This button is positioned on the right side of the screen using className override.
+          </p>
+        </div>
+
+        <div className="space-y-6">
+          {Array.from({ length: 35 }, (_, i) => (
+            <div key={i} className="p-4 bg-purple-50 rounded">
+              <h2 className="text-xl font-semibold mb-2">Content {i + 1}</h2>
+
+              <p>The back to top button appears on the right side instead of the default left.</p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+export const CustomStyling: Story = {
+  args: {
+    className: 'bg-blue-600 text-white border-blue-700 hover:bg-blue-700 shadow-xl',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Back to top button with custom styling using className prop.',
+      },
+    },
+  },
+  render: (args) => (
+    <div>
+      <BackToTop {...args} />
+
+      <div className="space-y-8 p-8">
+        <h1 className="text-3xl font-bold">Custom Styled Button</h1>
+
+        <div className="bg-blue-100 border border-blue-400 rounded p-4 mb-6">
+          <p className="text-blue-800">
+            This button has custom blue styling applied via the className prop.
+          </p>
+        </div>
+
+        <div className="space-y-6">
+          {Array.from({ length: 25 }, (_, i) => (
+            <div key={i} className="p-4 bg-blue-50 rounded">
+              <h2 className="text-xl font-semibold mb-2">Styled Section {i + 1}</h2>
+
+              <p>Custom styled back to top button with blue theme.</p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+export const AlwaysVisible: Story = {
+  args: {
+    threshold: 0,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Back to top button that is always visible (threshold set to 0).',
+      },
+    },
+  },
+  render: (args) => (
+    <div>
+      <BackToTop {...args} />
+
+      <div className="space-y-8 p-8">
+        <h1 className="text-3xl font-bold">Always Visible Button</h1>
+
+        <div className="bg-red-100 border border-red-400 rounded p-4 mb-6">
+          <p className="text-red-800">
+            This button is always visible because threshold is set to 0px.
+          </p>
+        </div>
+
+        <div className="space-y-6">
+          {Array.from({ length: 20 }, (_, i) => (
+            <div key={i} className="p-4 bg-red-50 rounded">
+              <h2 className="text-xl font-semibold mb-2">Always Visible {i + 1}</h2>
+
+              <p>The button is visible even at the top of the page.</p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+export const LongPageExample: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Comprehensive example with a very long page to test scroll behavior thoroughly.',
+      },
+    },
+  },
+  render: (args) => (
+    <div>
+      <BackToTop {...args} />
+
+      <div className="space-y-8 p-8">
+        <header className="mb-12">
+          <h1 className="text-4xl font-bold mb-4">Long Page Scroll Test</h1>
+
+          <p className="text-lg text-gray-600">
+            This page demonstrates the back to top functionality with extensive content. Scroll down
+            to see the button appear after 600px.
+          </p>
+        </header>
+
+        <section className="space-y-8">
+          <h2 className="text-2xl font-bold border-b pb-2">Article Content</h2>
+          {Array.from({ length: 100 }, (_, i) => (
+            <article key={i} className="p-6 bg-white border rounded-lg shadow-sm">
+              <h3 className="text-xl font-semibold mb-3">Article {i + 1}</h3>
+
+              <p className="mb-4">
+                Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                incididunt ut labore et dolore magna aliqua. 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. Excepteur sint occaecat cupidatat non proident, sunt in culpa
+                qui officia deserunt mollit anim id est laborum.
+              </p>
+              {i % 10 === 9 && (
+                <div className="mt-4 p-3 bg-gray-100 rounded">
+                  <p className="text-sm text-gray-600">
+                    📍 Checkpoint: You&apos;ve scrolled through {i + 1} articles. Use the back to
+                    top button to return to the beginning!
+                  </p>
+                </div>
+              )}
+            </article>
+          ))}
+        </section>
+
+        <footer className="mt-12 p-6 bg-gray-800 text-white rounded">
+          <p className="text-center">
+            🎉 You&apos;ve reached the end! Use the back to top button to scroll back up.
+          </p>
+        </footer>
+      </div>
+    </div>
+  ),
+};
+
+export const AccessibilityDemo: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Demonstration of accessibility features including keyboard navigation and screen reader support.',
+      },
+    },
+  },
+  render: (args) => (
+    <div>
+      <BackToTop {...args} />
+
+      <div className="space-y-8 p-8">
+        <h1 className="text-3xl font-bold">Accessibility Features Demo</h1>
+
+        <div className="bg-blue-50 border border-blue-200 rounded p-6">
+          <h2 className="text-xl font-bold text-blue-800 mb-4">Accessibility Features:</h2>
+
+          <ul className="list-disc list-inside space-y-2 text-blue-700">
+            <li>
+              <strong>Keyboard Navigation:</strong> Tab to focus, Enter or Space to activate
+            </li>
+
+            <li>
+              <strong>Screen Reader:</strong> Proper aria-label and hidden decorative icon
+            </li>
+
+            <li>
+              <strong>Focus Management:</strong> Visible focus indicators with ring
+            </li>
+
+            <li>
+              <strong>Responsive Text:</strong> &ldquo;Back to top&rdquo; text hidden on mobile,
+              available to screen readers
+            </li>
+
+            <li>
+              <strong>Semantic HTML:</strong> Proper button element with type attribute
+            </li>
+          </ul>
+        </div>
+
+        <div className="bg-green-50 border border-green-200 rounded p-4">
+          <h3 className="font-bold text-green-800 mb-2">Testing Instructions:</h3>
+
+          <ol className="list-decimal list-inside space-y-1 text-green-700 text-sm">
+            <li>Scroll down until the back to top button appears</li>
+
+            <li>Use Tab key to navigate to the button</li>
+
+            <li>Press Enter or Space to activate it</li>
+
+            <li>Test with a screen reader for proper announcements</li>
+          </ol>
+        </div>
+
+        <div className="space-y-6">
+          {Array.from({ length: 30 }, (_, i) => (
+            <div key={i} className="p-4 bg-gray-50 rounded">
+              <h3 className="text-lg font-semibold mb-2">Accessibility Section {i + 1}</h3>
+
+              <p>
+                This content tests the accessibility of the back to top button. The button should be
+                properly focusable and operable via keyboard.
+              </p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  ),
+};

package/src/components/backToTop/BackToTop.test.tsx

@@ -0,0 +1,57 @@
+import { BackToTop } from './BackToTop';
+import { render, screen, userEvent } from '../../test/renderers';
+
+describe('BackToTop component', () => {
+  const originalScrollTo = window.scrollTo;
+
+  beforeEach(() => {
+    Object.defineProperty(window, 'scrollTo', {
+      value: vi.fn(),
+      writable: true,
+    });
+
+    // Simulate scrollY (more modern than pageYOffset)
+    Object.defineProperty(window, 'pageYOffset', {
+      get: () => 700,
+      configurable: true,
+    });
+
+    Object.defineProperty(window, 'scrollY', {
+      get: () => 700,
+      configurable: true,
+    });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+    window.scrollTo = originalScrollTo;
+  });
+
+  it('renders correctly when scrolled down', async () => {
+    render(<BackToTop />);
+
+    // Trigger the scroll event manually to call toggleVisibility
+    window.dispatchEvent(new Event('scroll'));
+
+    // Wait for the component to update
+    const button = await screen.findByRole('button', { name: /back to top/i });
+
+    expect(button).toBeInTheDocument();
+  });
+
+  it('clickable and triggers scrollToTop', async () => {
+    const user = userEvent.setup();
+
+    render(<BackToTop />);
+
+    // Trigger the scroll event manually to call toggleVisibility
+    window.dispatchEvent(new Event('scroll'));
+
+    // Wait for the component to update and find the button
+    const button = await screen.findByRole('button', { name: /back to top/i });
+
+    await user.click(button);
+
+    expect(window.scrollTo).toHaveBeenCalledWith({ top: 0, behavior: 'smooth' });
+  });
+});