@tpzdsp/next-toolkit 1.2.9 → 1.4.0

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

package/src/components/backToTop/BackToTop.tsx

@@ -0,0 +1,131 @@
+'use client';
+
+import { type KeyboardEvent, useCallback, useEffect, useState } from 'react';
+
+import { LuArrowUp } from 'react-icons/lu';
+
+export type BackToTopProps = {
+  /** Scroll threshold in pixels before button appears */
+  threshold?: number;
+  /** Position from bottom in pixels */
+  bottom?: number;
+  /** Position from left in pixels */
+  left?: number;
+  /** Custom className for styling */
+  className?: string;
+};
+
+export const BackToTop = ({
+  threshold = 600,
+  bottom = 16,
+  left = 8,
+  className = '',
+}: BackToTopProps) => {
+  const [isVisible, setIsVisible] = useState(false);
+
+  // Throttle scroll events for better performance
+  const throttle = useCallback((func: () => void, delay: number) => {
+    let timeoutId: number | null = null;
+    let lastExecTime = 0;
+
+    return () => {
+      const currentTime = Date.now();
+
+      if (currentTime - lastExecTime > delay) {
+        func();
+        lastExecTime = currentTime;
+      } else {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+        }
+
+        timeoutId = window.setTimeout(
+          () => {
+            func();
+            lastExecTime = Date.now();
+          },
+          delay - (currentTime - lastExecTime),
+        );
+      }
+    };
+  }, []);
+
+  // Show button when page is scrolled down
+  const toggleVisibility = useCallback(() => {
+    if (typeof window !== 'undefined') {
+      setIsVisible(window.pageYOffset > threshold);
+    }
+  }, [threshold]);
+
+  // Scroll to top smoothly
+  const scrollToTop = useCallback(() => {
+    if (typeof window !== 'undefined') {
+      window.scrollTo({
+        top: 0,
+        behavior: 'smooth',
+      });
+    }
+  }, []);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') {
+      return;
+    }
+
+    const throttledToggleVisibility = throttle(toggleVisibility, 100);
+
+    // Check initial scroll position
+    toggleVisibility();
+
+    window.addEventListener('scroll', throttledToggleVisibility, { passive: true });
+
+    return () => {
+      window.removeEventListener('scroll', throttledToggleVisibility);
+    };
+  }, [toggleVisibility, throttle]);
+
+  // Handle keyboard interaction
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLButtonElement>) => {
+      if (event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault();
+        scrollToTop();
+      }
+    },
+    [scrollToTop],
+  );
+
+  if (!isVisible) {
+    return null;
+  }
+
+  return (
+    <button
+      type="button"
+      className={`
+        fixed z-50 inline-flex items-center gap-1
+        bg-white text-link border border-gray-300
+        rounded-md px-3 py-2 shadow-lg
+        hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2
+        transition-all duration-200 ease-in-out
+        ${className}
+      `.trim()}
+      // className={`fixed bottom-4 left-2 text-link gap-1 inline-flex items-center bg-white
+      //   ${className}`.trim()}
+      style={{
+        bottom: `${bottom}px`,
+        left: `${left}px`,
+      }}
+      onClick={scrollToTop}
+      onKeyDown={handleKeyDown}
+      aria-label="Scroll back to top of page"
+      title="Back to top"
+    >
+      <LuArrowUp size={20} aria-hidden="true" />
+
+      <span className="hidden sm:inline">Back to top</span>
+
+      <span className="sr-only sm:hidden">Back to top</span>
+    </button>
+  );
+};

package/src/components/chip/Chip.stories.tsx

@@ -0,0 +1,40 @@
+import { AiFillChrome } from 'react-icons/ai';
+
+/* eslint-disable storybook/no-renderer-packages */
+import type { Meta, StoryFn } from '@storybook/react';
+
+import { Chip, type ChipProps } from './Chip';
+import { Paragraph } from '../Paragraph/Paragraph';
+
+export default {
+  children: 'Chip',
+  component: Chip,
+} as Meta;
+
+const Template: StoryFn<ChipProps> = (args) => <Chip {...args} />;
+
+export const Default = Template.bind({});
+Default.args = {
+  children: 'Chip',
+};
+
+export const JustText = Template.bind({});
+JustText.args = {
+  children: 'Hello, this is some simple text',
+};
+
+export const ParagraphOfText = Template.bind({});
+ParagraphOfText.args = {
+  children: <Paragraph className="pb-0">Hello, this is a paragraph of text</Paragraph>,
+};
+
+export const TextWithIcon = Template.bind({});
+TextWithIcon.args = {
+  children: (
+    <div className="flex items-center justify-center gap-2">
+      <AiFillChrome className="text-base" />
+
+      <Paragraph className="pb-0">Hello, this is a paragraph of text</Paragraph>
+    </div>
+  ),
+};

package/src/components/chip/Chip.test.tsx

@@ -0,0 +1,31 @@
+import { Chip } from './Chip';
+import { render, screen } from '../../test/renderers';
+
+describe('Chip component', () => {
+  it('should render children correctly', () => {
+    render(
+      <Chip>
+        <p>Hello, World!</p>
+      </Chip>,
+    );
+
+    expect(screen.getByText('Hello, World!')).toBeInTheDocument();
+  });
+
+  it('should merge custom className correctly', () => {
+    render(<Chip className="bg-red-500 rounded-lg">Custom</Chip>);
+    const element = screen.getByText('Custom');
+
+    expect(element).toHaveClass('bg-red-500');
+    expect(element).toHaveClass('rounded-lg');
+  });
+
+  it('should override conflicting className using twMerge', () => {
+    render(<Chip className="px-2">Custom</Chip>);
+    const element = screen.getByText('Custom');
+
+    // Should NOT have original 'pt-[12px]' due to twMerge override
+    expect(element?.className).not.toMatch(/px-3/);
+    expect(element).toHaveClass('px-2');
+  });
+});

package/src/components/chip/Chip.tsx

@@ -0,0 +1,20 @@
+import { twMerge } from 'tailwind-merge';
+
+export type ChipProps = {
+  children: React.ReactNode;
+  className?: string;
+};
+
+export const Chip = ({ className, children }: ChipProps) => {
+  return (
+    <span
+      className={twMerge(
+        `inline-flex items-center rounded-lg bg-gray-200 px-3 py-1 text-sm font-medium
+        text-gray-800`,
+        className,
+      )}
+    >
+      {children}
+    </span>
+  );
+};