@tpzdsp/next-toolkit 1.7.0 → 1.9.0

package/src/components/Hint/Hint.stories.tsx

@@ -1,40 +1,58 @@
 /* eslint-disable storybook/no-renderer-packages */
-import type { Meta, StoryFn } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react';
 import { fn } from '@storybook/test';
 
-import { Hint, type HintProps } from './Hint';
+import { Hint } from './Hint';
 import { Button } from '../Button/Button';
 
-export default {
-  children: 'Hint',
+const meta: Meta<typeof Hint> = {
+  title: 'Components/Hint',
   component: Hint,
-} as Meta;
+  parameters: {
+    layout: 'padded',
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    children: {
+      control: false,
+      description: 'The content to display for the hint',
+    },
+    className: {
+      control: 'text',
+      description: 'Additional TailwindCSS classes to apply to the hint container',
+    },
+  },
+  args: {
+    children: 'Hint message',
+  },
+};
 
-const Template: StoryFn<HintProps> = (args) => <Hint {...args} />;
+export default meta;
 
-export const DefaultHint = Template.bind({});
-DefaultHint.args = {
-  children: 'Hint message',
-};
+type Story = StoryObj<typeof Hint>;
+
+export const Default: Story = {};
 
-export const CustomStyling = Template.bind({});
-CustomStyling.args = {
-  className: 'text-3xl',
-  children: 'Error message with extra large text',
+export const CustomStyling: Story = {
+  args: {
+    className: 'text-3xl',
+    children: 'Hint message with extra large text',
+  },
 };
 
-export const ComplexChildren = Template.bind({});
-ComplexChildren.args = {
-  children: (
-    <div>
-      Hint message with link and button{' '}
-      <a className="underline text-link" href="/">
-        Link
-      </a>
-      {/* // eslint-disable-next-line custom/padding-between-jsx-elements */}
-      <Button variant="primary" onClick={fn()}>
-        Click
-      </Button>
-    </div>
-  ),
+export const ComplexChildren: Story = {
+  args: {
+    children: (
+      <div>
+        Hint message with link and button{' '}
+        <a className="underline text-link" href="/">
+          Link
+        </a>
+        {}
+        <Button variant="primary" onClick={fn()}>
+          Click
+        </Button>
+      </div>
+    ),
+  },
 };

package/src/components/Paragraph/Paragraph.stories.tsx

@@ -1,30 +1,74 @@
 /* eslint-disable storybook/no-renderer-packages */
-import type { Meta, StoryFn } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react';
 
-import { Paragraph, type ParagraphProps } from './Paragraph';
+import { Paragraph } from './Paragraph';
+import { ExternalLink } from '../link/ExternalLink';
 
-export default {
-  children: 'Paragraph',
+const meta: Meta<typeof Paragraph> = {
+  title: 'Components/Paragraph',
   component: Paragraph,
-} as Meta;
+  parameters: {
+    layout: 'padded',
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    children: {
+      description: 'Content of the paragraph',
+      control: false,
+    },
+    className: {
+      description: 'Additional TailwindCSS classes to apply to the paragraph',
+      control: 'text',
+    },
+  },
+  args: {
+    children: 'Hello, this is some simple text',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Paragraph>;
+
+export const Default: Story = {};
 
-const Template: StoryFn<ParagraphProps> = (args) => <Paragraph {...args} />;
+export const CustomStyling: Story = {
+  args: {
+    className: 'text-yellow-800 p-2',
+    children: 'Hello, this is some simple text with custom styling',
+  },
+};
+
+export const LongText: Story = {
+  args: {
+    children:
+      'This is a very long paragraph. '.repeat(20) +
+      'It is used to test how the Paragraph component handles large amounts of text.',
+  },
+};
 
-export const JustText = Template.bind({});
-JustText.args = {
-  children: 'Hello, this is some simple text',
+export const WithLink: Story = {
+  args: {
+    children: (
+      <span>
+        This paragraph contains a <ExternalLink href="https://storybook.js.org/">link</ExternalLink>
+        .
+      </span>
+    ),
+  },
 };
 
-export const ImageAndText = Template.bind({});
-ImageAndText.args = {
-  children: (
-    <div>
-      <img
-        src="https://images.unsplash.com/photo-1563991655280-cb95c90ca2fb?w=500&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxzZWFyY2h8M3x8bm8lMjBjb3B5cmlnaHR8ZW58MHx8MHx8fDA%3D"
-        alt="Card"
-      />
-
-      <p>This is text about the image</p>
-    </div>
-  ),
+export const ImageAndText: Story = {
+  args: {
+    children: (
+      <div>
+        <img
+          src="https://images.unsplash.com/photo-1563991655280-cb95c90ca2fb?w=500&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxzZWFyY2h8M3x8bm8lMjBjb3B5cmlnaHR8ZW58MHx8MHx8fDA%3D"
+          alt="Card"
+        />
+
+        <p>This is text about the image</p>
+      </div>
+    ),
+  },
 };

package/src/components/Paragraph/Paragraph.tsx

@@ -1,10 +1,12 @@
+import { twMerge } from 'tailwind-merge';
+
 import type { ExtendProps } from '../../types/utils';
 
 export type ParagraphProps = ExtendProps<'p'>;
 
 export const Paragraph = ({ className, children, ...props }: ParagraphProps) => {
   return (
-    <p className={`pb-4 text-sm text-text-primary ${className}`} {...props}>
+    <p className={twMerge('pb-4 text-sm text-text-primary', className)} {...props}>
       {children}
     </p>
   );

package/src/components/SlidingPanel/SlidingPanel.stories.tsx

@@ -29,3 +29,102 @@ export const AllSlidingPanels: StoryObj<typeof SlidingPanel> = {
     </div>
   ),
 };
+
+export const WithAutoFocus: StoryObj<typeof SlidingPanel> = {
+  render: () => (
+    <SlidingPanel tabLabel="Auto Focus Demo" position="center-left">
+      <div>
+        <h3>Panel with Auto Focus</h3>
+
+        <p>The input below should be focused when the panel opens:</p>
+
+        <input data-autofocus placeholder="I will be focused automatically" />
+
+        <button type="button">Button</button>
+      </div>
+    </SlidingPanel>
+  ),
+};
+
+export const DefaultOpen: StoryObj<typeof SlidingPanel> = {
+  render: () => (
+    <SlidingPanel tabLabel="Always Open" position="center-right" defaultOpen>
+      <div>
+        <h3>Default Open Panel</h3>
+
+        <p>This panel starts open by default.</p>
+
+        <button type="button">Button 1</button>
+
+        <button type="button">Button 2</button>
+
+        <input placeholder="Input field" />
+      </div>
+    </SlidingPanel>
+  ),
+};
+
+export const FormExample: StoryObj<typeof SlidingPanel> = {
+  render: () => (
+    <SlidingPanel tabLabel="Contact Form" position="center-top">
+      <div>
+        <h3>Contact Form</h3>
+
+        <form>
+          <div style={{ marginBottom: '1rem' }}>
+            <label htmlFor="name">Name:</label>
+
+            <input id="name" type="text" placeholder="Your name" data-autofocus />
+          </div>
+
+          <div style={{ marginBottom: '1rem' }}>
+            <label htmlFor="email">Email:</label>
+
+            <input id="email" type="email" placeholder="your@email.com" />
+          </div>
+
+          <div style={{ marginBottom: '1rem' }}>
+            <label htmlFor="message">Message:</label>
+
+            <textarea id="message" placeholder="Your message"></textarea>
+          </div>
+
+          <button type="submit">Send Message</button>
+
+          <button type="button">Cancel</button>
+        </form>
+      </div>
+    </SlidingPanel>
+  ),
+};
+
+export const NoFocusableElements: StoryObj<typeof SlidingPanel> = {
+  render: () => (
+    <SlidingPanel tabLabel="No Focus Elements" position="center-left">
+      <div>
+        <h3>Panel Without Focusable Elements</h3>
+
+        <p>This panel only contains text and headings.</p>
+
+        <p>
+          It should still work properly with focus trapping, even though there are no buttons,
+          inputs, or other interactive elements.
+        </p>
+
+        <div>
+          <strong>Key Features:</strong>
+        </div>
+
+        <ul>
+          <li>Opens and closes properly</li>
+
+          <li>Focus trap works correctly</li>
+
+          <li>Escape key closes the panel</li>
+
+          <li>Focus returns to trigger button</li>
+        </ul>
+      </div>
+    </SlidingPanel>
+  ),
+};

package/src/components/SlidingPanel/SlidingPanel.tsx

@@ -1,8 +1,8 @@
 'use client';
 
-import { useState, useEffect, type ReactNode, useRef, useMemo, useCallback } from 'react';
+import { useState, useEffect, type ReactNode, useRef, useMemo, useId } from 'react';
 
-import { KeyboardKeys } from '../../utils';
+import { FocusTrap } from 'focus-trap-react';
 
 type Position = 'center-left' | 'center-right' | 'center-top' | 'center-bottom';
 
@@ -13,134 +13,69 @@ export type SlidingPanelProps = {
   defaultOpen?: boolean;
 };
 
-const TRAP_SELECTORS =
-  'a[href]:not([aria-hidden="true"]):not([hidden]), button:not([disabled]):not([aria-hidden="true"]):not([hidden]), input:not([disabled]):not([aria-hidden="true"]):not([hidden]), textarea:not([disabled]):not([aria-hidden="true"]):not([hidden]), select:not([disabled]):not([aria-hidden="true"]):not([hidden]), [tabindex]:not([tabindex="-1"]):not([aria-hidden="true"]):not([hidden])';
-
 export const SlidingPanel = ({
   children,
   tabLabel = 'Open',
   position = 'center-left',
   defaultOpen = false,
 }: SlidingPanelProps) => {
+  const id = useId();
+
   const [isVisible, setIsVisible] = useState(defaultOpen);
+  const [isTrapActive, setIsTrapActive] = useState(defaultOpen);
   const [panelDimensions, setPanelDimensions] = useState({ width: 0, height: 0 });
-  const panelRef = useRef<HTMLDivElement>(null);
-  const triggerRef = useRef<HTMLElement | null>(null); // store previously focused element
 
-  const openPanel = () => {
-    triggerRef.current = document.activeElement as HTMLElement;
-    setIsVisible(true);
-  };
+  const panelRef = useRef<HTMLDivElement>(null);
+  const buttonRef = useRef<HTMLButtonElement | null>(null);
 
-  const closePanel = useCallback(() => {
-    setIsVisible(false);
-  }, []);
+  // Required for the `escapeDeactivates` function as these options are an object and only
+  // capture their environment once, so without a ref, `isVisible` would only ever be
+  // `false` inside the callback, even if it's change. A `useCallback` doesn't help because
+  // it creates a new function each time, so the event would still only capture the first created function.
+  const isVisibleRef = useRef(isVisible);
+  // tracks if the focus trap was deactivated by clicking outside the trap
+  const deactivatedByClick = useRef(false);
 
-  // Measure panel dimensions when visible
   useEffect(() => {
-    if (isVisible && panelRef.current) {
-      const updateDimensions = () => {
-        if (panelRef.current) {
-          const rect = panelRef.current.getBoundingClientRect();
-
-          const newDimensions = { width: rect.width, height: rect.height };
-
-          if (
-            newDimensions.width !== panelDimensions.width ||
-            newDimensions.height !== panelDimensions.height
-          ) {
-            setPanelDimensions(newDimensions);
-          }
-        }
-      };
-
-      // Initial measurement
-      updateDimensions();
+    isVisibleRef.current = isVisible;
 
-      // Use ResizeObserver to detect changes
-      const resizeObserver = new ResizeObserver(updateDimensions);
+    deactivatedByClick.current = false;
 
-      resizeObserver.observe(panelRef.current);
-
-      return () => resizeObserver.disconnect();
-    }
-  }, [isVisible, panelDimensions.height, panelDimensions.width]);
-
-  // move focus into panel when opened, restore focus to correct element when closed
-  useEffect(() => {
-    if (isVisible && panelRef.current) {
-      const els = Array.from(panelRef.current.querySelectorAll<HTMLElement>(TRAP_SELECTORS));
-
-      if (els.length > 0) {
-        els[0].focus();
-      } else {
-        panelRef.current.focus();
-      }
-    } else if (!isVisible && triggerRef.current) {
-      triggerRef.current.focus();
-    }
+    setIsTrapActive(isVisible);
   }, [isVisible]);
 
-  // trap focus while open
+  // Measure panel dimensions when visible or when panel content changes
   useEffect(() => {
-    if (!isVisible || !panelRef.current) {
+    if (!panelRef.current) {
       return;
     }
 
-    const panel = panelRef.current;
-
-    const moveFocus = (direction: 'next' | 'prev') => {
-      const els = Array.from(panel.querySelectorAll<HTMLElement>(TRAP_SELECTORS));
-
-      if (!els.length) {
-        panel.focus();
-
-        return true;
-      }
-
-      const first = els[0];
-      const last = els[els.length - 1];
-      const active = document.activeElement;
-
-      if (direction === 'next' && active === last) {
-        first.focus();
-
-        return true;
-      }
-
-      if (direction === 'prev' && active === first) {
-        last.focus();
+    const updateDimensions = () => {
+      if (panelRef.current) {
+        const rect = panelRef.current.getBoundingClientRect();
+        const newDimensions = { width: rect.width, height: rect.height };
 
-        return true;
+        if (
+          newDimensions.width !== panelDimensions.width ||
+          newDimensions.height !== panelDimensions.height
+        ) {
+          setPanelDimensions(newDimensions);
+        }
       }
-
-      return false;
     };
 
-    const handleKey = (event: KeyboardEvent) => {
-      if (event.key === KeyboardKeys.Escape) {
-        event.preventDefault();
-        closePanel();
-
-        return;
-      }
-
-      if (event.key !== KeyboardKeys.Tab) {
-        return;
-      }
+    // Initial measurement
+    updateDimensions();
 
-      // only if focus was moved do we prevent the default behaviour
-      if (moveFocus(event.shiftKey ? 'prev' : 'next')) {
-        event.preventDefault();
-      }
-    };
+    // Use ResizeObserver to detect content changes
+    const resizeObserver = new ResizeObserver(updateDimensions);
 
-    panel.addEventListener('keydown', handleKey);
+    resizeObserver.observe(panelRef.current);
 
     return () => {
-      panel.removeEventListener('keydown', handleKey);
+      resizeObserver.disconnect();
     };
-  }, [closePanel, isVisible]);
+  }, [isVisible, panelDimensions.height, panelDimensions.width]);
 
   const panelBase =
     'absolute bg-white shadow-lg p-4 flex flex-col transition-transform duration-300 ease-in-out overflow-auto z-30';
@@ -201,6 +136,14 @@ export const SlidingPanel = ({
     return {};
   }, [isVisible, panelDimensions.height, panelDimensions.width, position]);
 
+  const openPanel = () => {
+    setIsVisible(true);
+  };
+
+  const closePanel = () => {
+    setIsVisible(false);
+  };
+
   return (
     <div className="absolute inset-0 z-30 overflow-hidden pointer-events-none sliding-panel">
       <button
@@ -208,21 +151,87 @@ export const SlidingPanel = ({
         style={getButtonStyle}
         onClick={() => (isVisible ? closePanel() : openPanel())}
         aria-expanded={isVisible}
-        aria-controls="sliding-panel"
+        aria-controls={id}
+        ref={buttonRef}
+        type="button"
       >
         {isVisible ? `Close ${tabLabel}` : `Open ${tabLabel}`}
       </button>
 
-      <div
-        ref={panelRef}
-        tabIndex={-1}
-        id="sliding-panel"
-        className={`${panelBase} ${panelLayout} pointer-events-auto`}
-        aria-hidden={!isVisible}
-        inert={!isVisible}
+      <FocusTrap
+        active={isTrapActive}
+        focusTrapOptions={{
+          escapeDeactivates: () => {
+            deactivatedByClick.current = false;
+
+            if (isVisibleRef.current) {
+              closePanel();
+            }
+
+            return false;
+          },
+          clickOutsideDeactivates: () => {
+            deactivatedByClick.current = true; // mark as mouse-driven
+
+            return true; // still allow it to deactivate
+          },
+          // eslint-disable-next-line sonarjs/function-return-type
+          setReturnFocus: (target) => {
+            // if the user has clicked outside the focus trap we shouldn't return focus as it will steal focus from the element they clicked on
+            return deactivatedByClick.current ? false : target;
+          },
+          onDeactivate: () => {
+            setIsTrapActive(false);
+          },
+          onActivate: () => {
+            setIsTrapActive(true);
+          },
+          /**
+           * Emergency fallback focus function for FocusTrap.
+           *
+           * This function is automatically called by FocusTrap whenever it cannot find
+           * any tabbable elements within the panel. This commonly occurs in scenarios like:
+           *
+           * - Panel opens but async content hasn't loaded yet
+           * - Panel is closing and content is being unmounted
+           * - User presses Escape and TableFilters content disappears
+           * - Dynamic content changes temporarily remove all focusable elements
+           *
+           * Without this fallback, FocusTrap throws the error:
+           * "Your focus-trap must have at least one container with at least one tabbable node in it at all times"
+           *
+           * The function ensures there's always a focusable element available by:
+           * 1. Looking for our guaranteed hidden fallback element with [data-fallback-focus]
+           * 2. Making it temporarily focusable (tabIndex = 0)
+           * 3. Returning it to FocusTrap as a safe focus target
+           * 4. Using document.body as ultimate fallback if something goes wrong
+           *
+           * This is especially crucial for complex content like ObservationTableManager
+           * where TableFilters has async operations that can cause content to disappear
+           * during panel lifecycle events.
+           *
+           * @returns HTMLElement - The element FocusTrap should focus on as a fallback
+           */
+          fallbackFocus: () => {
+            return panelRef.current ?? buttonRef.current ?? document.body;
+          },
+        }}
       >
-        <div className="mt-4">{children}</div>
-      </div>
+        <div
+          ref={panelRef}
+          tabIndex={-1}
+          id={id}
+          role="dialog"
+          aria-modal="true"
+          aria-label={`Sliding panel for ${tabLabel}`}
+          className={`${panelBase} ${panelLayout} pointer-events-auto`}
+          aria-hidden={!isVisible}
+          inert={!isVisible}
+          onPointerDown={() => (!isTrapActive ? setIsTrapActive(true) : void 0)}
+        >
+          <div className="mt-4">{children}</div>
+        </div>
+      </FocusTrap>
     </div>
   );
 };

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

@@ -1,40 +1,62 @@
+/* eslint-disable storybook/no-renderer-packages */
 import { AiFillChrome } from 'react-icons/ai';
 
-/* eslint-disable storybook/no-renderer-packages */
-import type { Meta, StoryFn } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react';
 
-import { Chip, type ChipProps } from './Chip';
+import { Chip } from './Chip';
 import { Paragraph } from '../Paragraph/Paragraph';
 
-export default {
-  children: 'Chip',
+const meta: Meta<typeof Chip> = {
+  title: 'Components/Chip',
   component: Chip,
-} as Meta;
+  parameters: {
+    layout: 'padded',
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    children: {
+      description: 'Content of the chip',
+      control: false,
+    },
+    className: {
+      description: 'Additional TailwindCSS classes to apply',
+      control: 'text',
+    },
+  },
+  args: {
+    children: 'Hello, this is some simple Chip',
+  },
+};
 
-const Template: StoryFn<ChipProps> = (args) => <Chip {...args} />;
+export default meta;
 
-export const Default = Template.bind({});
-Default.args = {
-  children: 'Chip',
-};
+type Story = StoryObj<typeof Chip>;
 
-export const JustText = Template.bind({});
-JustText.args = {
-  children: 'Hello, this is some simple text',
-};
+export const Default: Story = {};
 
-export const ParagraphOfText = Template.bind({});
-ParagraphOfText.args = {
-  children: <Paragraph className="pb-0">Hello, this is a paragraph of text</Paragraph>,
+export const ParagraphOfText: Story = {
+  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" />
+export const TextWithIcon: Story = {
+  args: {
+    children: (
+      <div className="flex items-center justify-center gap-2">
+        <AiFillChrome className="text-base" />
+
+        <Paragraph className="pb-0">
+          Hello, this is a Chip container with a paragraph of text
+        </Paragraph>
+      </div>
+    ),
+  },
+};
 
-      <Paragraph className="pb-0">Hello, this is a paragraph of text</Paragraph>
-    </div>
-  ),
+export const CustomStyling: Story = {
+  args: {
+    className: 'bg-blue-100 text-blue-800 px-4 py-2 rounded-full',
+    children: 'Custom styled chip',
+  },
 };