@tpzdsp/next-toolkit 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpzdsp/next-toolkit",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "A reusable React component library for Next.js applications",
   "type": "module",
   "private": false,
@@ -164,6 +164,8 @@
     "eslint-plugin-react-refresh": "^0.4.20",
     "eslint-plugin-sonarjs": "^3.0.4",
     "eslint-plugin-storybook": "^9.0.18",
+    "focus-trap": "^7.6.5",
+    "focus-trap-react": "^11.0.4",
     "geojson": "^0.5.0",
     "globals": "^16.3.0",
     "husky": "^9.1.7",
@@ -208,6 +210,8 @@
     "@types/geojson": "^7946.0.16",
     "@types/jsonwebtoken": "^9.0.10",
     "date-fns": "^4.1.0",
+    "focus-trap": "^7.6.5",
+    "focus-trap-react": "^11.0.4",
     "geojson": "^0.5.0",
     "jsonwebtoken": "^9.0.2",
     "next": "^15.4.2",
@@ -240,6 +244,12 @@
     "date-fns": {
       "optional": true
     },
+    "focus-trap": {
+      "optional": true
+    },
+    "focus-trap-react": {
+      "optional": true
+    },
     "geojson": {
       "optional": true
     },

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

@@ -1,56 +1,83 @@
+/* eslint-disable storybook/no-renderer-packages */
 import { FaChevronRight } from 'react-icons/fa6';
 
-/* eslint-disable storybook/no-renderer-packages */
-import type { Meta, StoryFn } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react';
 
-import { Card, type CardProps } from './Card';
+import { Card } from './Card';
+import { ExternalLink } from '../link/ExternalLink';
 import { Paragraph } from '../Paragraph/Paragraph';
 
-export default {
-  children: 'Card',
+const meta: Meta<typeof Card> = {
+  title: 'Components/Card',
   component: Card,
-} as Meta;
+  parameters: {
+    layout: 'padded',
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    children: {
+      description: 'Content of the card',
+      control: false,
+    },
+    className: {
+      description: 'Additional TailwindCSS classes to apply',
+      control: 'text',
+    },
+  },
+  args: {
+    children: 'Hello, this is some simple text',
+  },
+};
+
+export default meta;
 
-const Template: StoryFn<CardProps> = (args) => <Card {...args} />;
+type Story = StoryObj<typeof Card>;
 
-export const JustText = Template.bind({});
-JustText.args = {
-  children: 'Hello, this is some simple text',
+export const Default: Story = {};
+
+export const ParagraphOfText: Story = {
+  args: {
+    children: <Paragraph>Hello, this is some simple text</Paragraph>,
+  },
 };
 
-export const ParagraphOfText = Template.bind({});
-ParagraphOfText.args = {
-  children: <p>Hello, this is some simple text</p>,
+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>
+    ),
+  },
 };
 
-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 ComplexChildren: Story = {
+  args: {
+    children: (
+      <>
+        <ExternalLink
+          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" />
+        </ExternalLink>
+
+        <Paragraph>Some descriptive text</Paragraph>
+      </>
+    ),
+  },
 };
 
-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>
-    </>
-  ),
+export const CustomStyling: Story = {
+  args: {
+    className: 'bg-blue-100 text-blue-800 p-4 rounded-lg shadow-lg',
+    children: 'Custom styled card',
+  },
 };

package/src/components/ErrorBoundary/ErrorFallback.stories.tsx

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 
 import { ErrorFallback } from './ErrorFallback';
 import { ApiError } from '../../errors/ApiError';
-import { HttpStatus } from '../../http';
+import { HttpStatus } from '../../http/constants';
 
 const meta = {
   title: 'Components/ErrorFallback',

package/src/components/ErrorBoundary/ErrorFallback.tsx

@@ -1,3 +1,5 @@
+'use client';
+
 import { useId } from 'react';
 
 import { type FallbackProps } from 'react-error-boundary';

package/src/components/ErrorText/ErrorText.stories.tsx

@@ -1,34 +1,53 @@
 /* eslint-disable storybook/no-renderer-packages */
-import type { Meta, StoryFn } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react';
 
-import { ErrorText, type ErrorTextProps } from './ErrorText';
+import { ErrorText } from './ErrorText';
+import { ExternalLink } from '../link/ExternalLink';
 
-export default {
-  children: 'Error text',
+const meta: Meta<typeof ErrorText> = {
+  title: 'Components/ErrorText',
   component: ErrorText,
-} as Meta;
+  parameters: {
+    layout: 'padded',
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    children: {
+      description: 'The content to display for the error',
+      control: false,
+    },
+    className: {
+      description: 'Additional TailwindCSS classes to apply',
+      control: 'text',
+    },
+  },
+  args: {
+    children: 'Error message',
+  },
+};
 
-const Template: StoryFn<ErrorTextProps> = (args) => <ErrorText {...args} />;
+export default meta;
 
-export const DefaultError = Template.bind({});
-DefaultError.args = {
-  children: 'Error message',
-};
+type Story = StoryObj<typeof ErrorText>;
+
+export const Default: Story = {};
 
-export const CustomStyling = Template.bind({});
-CustomStyling.args = {
-  className: 'text-3xl',
-  children: 'Error message with large text',
+export const CustomStyling: Story = {
+  args: {
+    className: 'text-3xl',
+    children: 'Custom styled error message',
+  },
 };
 
-export const ComplexChildren = Template.bind({});
-ComplexChildren.args = {
-  children: (
-    <div>
-      Error message with link{' '}
-      <a className="underline text-link" href="/">
-        Link
-      </a>
-    </div>
-  ),
+export const ComplexChildren: Story = {
+  args: {
+    children: (
+      <div>
+        Error message with{' '}
+        <ExternalLink className="underline text-link" href="/">
+          Link
+        </ExternalLink>
+      </div>
+    ),
+  },
 };

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

package/src/errors/ApiError.ts

@@ -2,7 +2,7 @@
 
 import z from 'zod/v4';
 
-import { HttpStatus, HttpStatusText } from '../http';
+import { HttpStatus, HttpStatusText } from '../http/constants';
 
 /**
  * Schema defining the JSON shape of error responses returned by a server. (The proxy is where
@@ -53,7 +53,13 @@ export class ApiError extends Error implements z.output<typeof ApiErrorSchema> {
     this.name = 'ApiError';
     this.status = status;
     this.details = details ?? null;
-    this.digest = crypto.randomUUID();
+    // Crypto is a NodeJS and browser global; use it if available, but fallback to a pseudo-random string otherwise.
+    // This is due to Storybook not providing the `crypto` global in some environments (e.g., Jest).
+    this.digest =
+      typeof crypto?.randomUUID === 'function'
+        ? crypto.randomUUID()
+        : // eslint-disable-next-line sonarjs/pseudo-random
+          Math.random().toString(36).slice(2);
     this.rehydrated = options?.rehydrated ?? false;
 
     // Maintains proper stack trace for where our error was thrown (only available on V8)

package/src/http/constants.ts

@@ -99,6 +99,8 @@ export const Header = {
   CsvHeader: 'CSV-Header',
   XTotalItems: 'X-Total-Items',
   XRequestId: 'X-Request-ID',
+  ApiVersion: 'API-Version',
+  CacheControl: 'Cache-Control',
 } as const;
 
 /**

package/src/map/LayerSwitcherControl.ts

@@ -1,11 +1,11 @@
 /* eslint-disable no-restricted-syntax */
+import { createFocusTrap } from 'focus-trap';
+import type { FocusTrap } from 'focus-trap';
 import { Map } from 'ol';
 import { Control } from 'ol/control';
 import type { Options as ControlOptions } from 'ol/control/Control';
 import BaseLayer from 'ol/layer/Base';
 
-import { KeyboardKeys } from '../utils';
-
 const TIMEOUT = 300; // Match CSS transition duration
 const ARIA_LABEL = 'aria-label';
 
@@ -16,7 +16,8 @@ export class LayerSwitcherControl extends Control {
   map!: Map;
   panel!: HTMLElement;
   liveRegion!: HTMLElement;
-  isCollapsed = true;
+  isOpen = false;
+  private focusTrap: FocusTrap | null = null;
 
   constructor(layers: BaseLayer[], options?: ControlOptions) {
     const button = document.createElement('button');
@@ -70,9 +71,6 @@ export class LayerSwitcherControl extends Control {
     this.panel.setAttribute('aria-modal', 'true');
     this.panel.setAttribute(ARIA_LABEL, 'Basemap switcher');
 
-    // Add a keydown listener to the panel for Escape key
-    this.panel.addEventListener('keydown', this.handlePanelKeyDown);
-
     // Create the header for the close button
     const header = document.createElement('div');
 
@@ -87,7 +85,6 @@ export class LayerSwitcherControl extends Control {
     closeBtn.type = 'button';
     closeBtn.addEventListener('click', () => {
       this.toggleLayerSwitcher();
-      this.focusToggleButton();
     });
     header.appendChild(closeBtn);
 
@@ -124,6 +121,29 @@ export class LayerSwitcherControl extends Control {
     this.panel.appendChild(header);
     this.panel.appendChild(content);
 
+    // Create focus trap once - will be activated/deactivated as needed
+    this.focusTrap = createFocusTrap(this.panel, {
+      clickOutsideDeactivates: (event) => {
+        // if the user happens to click on the open button again we let the button handle the click event, not the focus trap
+        if (button.contains(event.target as Node)) {
+          return true;
+        }
+
+        this.toggleLayerSwitcher();
+
+        return false;
+      },
+      escapeDeactivates: () => {
+        this.toggleLayerSwitcher();
+
+        return false;
+      },
+      returnFocusOnDeactivate: true,
+      fallbackFocus: () => {
+        return this.panel;
+      },
+    });
+
     button.addEventListener('click', this.toggleLayerSwitcher, false);
   }
 
@@ -142,22 +162,6 @@ export class LayerSwitcherControl extends Control {
       .find((layer: BaseLayer) => layer.get('name') === layerName);
   }
 
-  private focusFirstButton() {
-    const firstBtn = this.panel.querySelector(
-      'button:not(.ol-layer-switcher-close)',
-    ) as HTMLButtonElement | null;
-
-    firstBtn?.focus();
-  }
-
-  private focusToggleButton() {
-    const toggleBtn = this.element.querySelector(
-      'button.ol-layer-switcher-toggle',
-    ) as HTMLButtonElement | null;
-
-    toggleBtn?.focus();
-  }
-
   private announceBasemapChange(layerName: string) {
     if (this.liveRegion) {
       this.liveRegion.textContent = `Basemap changed to ${layerName}`;
@@ -181,59 +185,33 @@ export class LayerSwitcherControl extends Control {
 
   // Arrow function: 'this' is always bound to the class instance
   toggleLayerSwitcher = () => {
-    if (this.isCollapsed) {
+    if (!this.isOpen) {
       this.element.appendChild(this.panel);
+
       requestAnimationFrame(() => {
         this.panel.classList.add('open'); // Ensure animation works after adding to DOM
 
-        // Focus the first basemap button (skip the close button)
-        this.focusFirstButton();
+        // Activate the existing focus trap
+        this.focusTrap?.activate();
       });
     } else {
       this.panel.classList.remove('open');
+
+      // Deactivate focus trap but keep the instance
+      this.focusTrap?.deactivate();
+
       setTimeout(() => {
         this.element.removeChild(this.panel);
       }, TIMEOUT); // Matches CSS transition time to prevent flickering
     }
 
-    this.isCollapsed = !this.isCollapsed;
+    this.isOpen = !this.isOpen;
 
     // Update aria-expanded on the toggle button
     const toggleBtn = this.element.querySelector('button.ol-layer-switcher-toggle');
 
     if (toggleBtn) {
-      toggleBtn.setAttribute('aria-expanded', (!this.isCollapsed).toString());
-    }
-  };
-
-  // Arrow function for panel keydown
-  handlePanelKeyDown = (event: KeyboardEvent) => {
-    // Focus trap: cycle focus within the panel
-    if (event.key === KeyboardKeys.Tab) {
-      const focusable = Array.from(this.panel.querySelectorAll('button')) as HTMLButtonElement[];
-
-      if (focusable.length === 0) {
-        return;
-      }
-
-      const first = focusable[0];
-      const last = focusable[focusable.length - 1];
-
-      if (!event.shiftKey && document.activeElement === last) {
-        event.preventDefault();
-        first.focus();
-      } else if (event.shiftKey && document.activeElement === first) {
-        event.preventDefault();
-        last.focus();
-      }
-    }
-
-    // Escape closes the panel and returns focus to the toggle button
-    if (event.key === KeyboardKeys.Escape) {
-      this.toggleLayerSwitcher();
-
-      // Focus back on the basemap switcher button
-      this.focusToggleButton();
+      toggleBtn.setAttribute('aria-expanded', this.isOpen.toString());
     }
   };
 
@@ -276,4 +254,14 @@ export class LayerSwitcherControl extends Control {
       btn.setAttribute('aria-pressed', isActive ? 'true' : 'false');
     });
   };
+
+  // Cleanup method - call this when removing the control
+  destroy() {
+    // Deactivate and destroy focus trap
+    if (this.focusTrap) {
+      this.focusTrap.deactivate();
+    }
+
+    this.focusTrap = null;
+  }
 }

package/src/utils/utils.ts

@@ -1,4 +1,4 @@
-import { decode } from 'jsonwebtoken';
+import { verify } from 'jsonwebtoken';
 import { twMerge } from 'tailwind-merge';
 
 import type { Credentials, DecodedJWT } from '../types/auth';
@@ -9,10 +9,19 @@ export const decodeAuthToken = (token: string): Credentials | null => {
   }
 
   try {
-    const user = decode(token) as unknown as DecodedJWT;
+    // eslint-disable-next-line no-undef
+    const secret = process.env.JWT_SECRET;
+
+    if (!secret) {
+      throw new Error('JWT secret not set');
+    }
+
+    const user = verify(token, secret) as DecodedJWT;
 
     return { token, user };
-  } catch {
+  } catch (error) {
+    console.error('Error decoding auth token:', error);
+
     return null;
   }
 };