@tpzdsp/next-toolkit 1.13.0 → 1.14.1

package/src/components/layout/header/Header.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Header } from './Header';
+import type { Credentials } from '../../../types/auth';
+import type { NavLink } from '../../../types/navigation';
+
+const navLinks: NavLink[] = [
+  { label: 'Home', url: '/', isExternal: false },
+  { label: 'API', url: '/api-docs', isExternal: false },
+  { label: 'Support', url: 'https://example.com/support', isExternal: true },
+];
+
+const authenticatedCredentials: Credentials = {
+  token: 'mock-token',
+  user: {
+    name: 'Jamie Taylor',
+    email: 'jamie.taylor@example.com',
+    groupInfoIds: ['group-1', 'group-2'],
+  },
+};
+
+export default {
+  title: 'Components/Layout/Header',
+  component: Header,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Header with DSP branding, navigation, and auth state. Includes responsive nav and client-side auth links.',
+      },
+    },
+  },
+  args: {
+    dspUrl: 'https://environment.data.gov.uk',
+    appName: 'Wetlands Inventory',
+    navLinks,
+    credentials: null,
+  },
+} as Meta<typeof Header>;
+
+export const Default: StoryObj<typeof Header> = {};
+
+export const Authenticated: StoryObj<typeof Header> = {
+  args: {
+    credentials: authenticatedCredentials,
+  },
+};

package/src/components/layout/header/Header.test.tsx

@@ -0,0 +1,36 @@
+import { Header } from './Header';
+import { render, screen } from '../../../test/renderers';
+import type { NavLink } from '../../../types/navigation';
+
+const NAV_LINKS: NavLink[] = [
+  { label: 'Home', url: '/', isExternal: false },
+  { label: 'API', url: '/api-docs', isExternal: false },
+  { label: 'Support', url: 'https://example.com/support', isExternal: true },
+];
+
+describe('Header', () => {
+  it('renders the primary brand links and app name', async () => {
+    render(
+      <Header
+        credentials={null}
+        dspUrl="https://example.com"
+        appName="Wetlands Inventory"
+        navLinks={NAV_LINKS}
+      />,
+    );
+
+    expect(
+      screen.getByRole('link', {
+        name: /department for environment food & rural affairs/i,
+      }),
+    ).toBeInTheDocument();
+
+    expect(screen.getByRole('link', { name: /data services platform/i })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: /wetlands inventory/i })).toBeInTheDocument();
+
+    const loginLink = await screen.findByRole('link', { name: /login/i });
+
+    expect(loginLink).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /open menu/i })).toBeInTheDocument();
+  });
+});

package/src/components/layout/header/HeaderAuthClient.test.tsx

@@ -0,0 +1,45 @@
+import { HeaderAuthClient } from './HeaderAuthClient';
+import { render, screen } from '../../../test/renderers';
+import type { Credentials } from '../../../types/auth';
+
+const AUTH_CREDENTIALS: Credentials = {
+  token: 'token-123',
+  user: {
+    name: 'Jamie Taylor',
+    email: 'jamie.taylor@example.com',
+    groupInfoIds: ['group-1'],
+  },
+};
+
+describe('HeaderAuthClient', () => {
+  beforeEach(() => {
+    globalThis.history.pushState({}, '', '/header-test');
+  });
+
+  it('renders guest state with login link', async () => {
+    render(<HeaderAuthClient hostname="https://example.com" credentials={null} />);
+
+    expect(screen.getByText(/welcome,/i)).toBeInTheDocument();
+    expect(screen.getByText(/guest/i)).toBeInTheDocument();
+
+    const loginLink = await screen.findByRole('link', { name: /login/i });
+
+    expect(loginLink).toHaveAttribute(
+      'href',
+      `https://example.com/login?redirect-uri=${encodeURIComponent(globalThis.location.href)}`,
+    );
+  });
+
+  it('renders authenticated state with logout link', async () => {
+    render(<HeaderAuthClient hostname="https://example.com" credentials={AUTH_CREDENTIALS} />);
+
+    expect(screen.getByText(/jamie.taylor@example.com/i)).toBeInTheDocument();
+
+    const logoutLink = await screen.findByRole('link', { name: /logout/i });
+
+    expect(logoutLink).toHaveAttribute(
+      'href',
+      `https://example.com/api/logout?redirect-uri=${encodeURIComponent(globalThis.location.href)}`,
+    );
+  });
+});

package/src/components/layout/header/HeaderNavClient.test.tsx

@@ -0,0 +1,44 @@
+import { HeaderNavClient } from './HeaderNavClient';
+import { render, screen, userEvent } from '../../../test/renderers';
+import type { NavLink } from '../../../types/navigation';
+
+const NAV_LINKS: NavLink[] = [
+  { label: 'Home', url: '/', isExternal: false },
+  { label: 'API', url: '/api-docs', isExternal: false },
+  { label: 'Support', url: 'https://example.com/support', isExternal: true },
+];
+
+describe('HeaderNavClient', () => {
+  it('renders both navigation regions', () => {
+    render(<HeaderNavClient navLinks={NAV_LINKS} />);
+
+    expect(
+      screen.getByRole('navigation', { name: /small screen navigation/i }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('navigation', { name: /large screen navigation/i }),
+    ).toBeInTheDocument();
+  });
+
+  it('shows menu items in the small-screen dropdown', async () => {
+    render(<HeaderNavClient navLinks={NAV_LINKS} />);
+
+    const user = userEvent.setup();
+
+    await user.click(screen.getByRole('button', { name: /open menu/i }));
+
+    expect(await screen.findByRole('menuitem', { name: /home/i })).toBeInTheDocument();
+    expect(await screen.findByRole('menuitem', { name: /api/i })).toBeInTheDocument();
+    expect(await screen.findByRole('menuitem', { name: /support/i })).toBeInTheDocument();
+  });
+
+  it('renders large-screen links for navigation', () => {
+    render(<HeaderNavClient navLinks={NAV_LINKS} />);
+
+    const supportLink = screen.getByRole('link', { name: /support/i });
+
+    expect(supportLink).toHaveAttribute('href', 'https://example.com/support');
+    expect(screen.getByRole('link', { name: /home/i })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: /api/i })).toBeInTheDocument();
+  });
+});

package/src/components/layout/header/HeaderNavClient.tsx

@@ -23,12 +23,15 @@ const InternalNavItem = ({ label, url, icon, ...props }: DropdownMenuItem<NavLin
   </Link>
 );
 
-const NavItem = ({ isExternal, ...props }: DropdownMenuItem<NavLink>) => {
+const NavItem = ({ url, openInNewTab, ...props }: DropdownMenuItem<NavLink>) => {
+  const isExternal = /^https?:\/\//.test(url);
+  const newTabProps = openInNewTab ? { target: '_blank' as const, rel: 'noopener noreferrer' } : {};
+
   if (isExternal) {
-    return <ExternalNavItem {...props} />;
+    return <ExternalNavItem url={url} {...newTabProps} {...props} />;
   }
 
-  return <InternalNavItem {...props} />;
+  return <InternalNavItem url={url} {...newTabProps} {...props} />;
 };
 
 export const HeaderNavClient = ({ navLinks }: HeaderNavClientProps) => {

package/src/components/link/ExternalLink.test.tsx

@@ -0,0 +1,102 @@
+import { render, screen } from '@testing-library/react';
+
+import { ExternalLink } from './ExternalLink';
+
+describe('ExternalLink', () => {
+  it('renders with children', () => {
+    render(<ExternalLink href="https://example.com">Visit Example</ExternalLink>);
+
+    const link = screen.getByRole('link', { name: /Visit Example/i });
+
+    expect(link).toBeInTheDocument();
+  });
+
+  it('sets target="_blank" to open in new tab', () => {
+    render(<ExternalLink href="https://example.com">External Link</ExternalLink>);
+
+    const link = screen.getByRole('link');
+
+    expect(link).toHaveAttribute('target', '_blank');
+  });
+
+  it('sets rel="noopener noreferrer" for security', () => {
+    render(<ExternalLink href="https://example.com">External Link</ExternalLink>);
+
+    const link = screen.getByRole('link');
+
+    expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+  });
+
+  it('includes screen reader text indicating new tab', () => {
+    render(<ExternalLink href="https://example.com">Visit Site</ExternalLink>);
+
+    // The accessible name should include the "(opens in new tab)" text
+    const link = screen.getByRole('link', { name: /Visit Site\(opens in new tab\)/i });
+
+    expect(link).toBeInTheDocument();
+  });
+
+  it('applies custom className', () => {
+    render(
+      <ExternalLink href="https://example.com" className="custom-class">
+        Link
+      </ExternalLink>,
+    );
+
+    const link = screen.getByRole('link');
+
+    expect(link).toHaveClass('custom-class');
+  });
+
+  it('preserves default link styling classes', () => {
+    render(<ExternalLink href="https://example.com">Link</ExternalLink>);
+
+    const link = screen.getByRole('link');
+
+    expect(link).toHaveClass('text-link');
+    expect(link).toHaveClass('underline');
+  });
+
+  it('applies href attribute correctly', () => {
+    render(<ExternalLink href="https://example.com">Link</ExternalLink>);
+
+    const link = screen.getByRole('link');
+
+    expect(link).toHaveAttribute('href', 'https://example.com');
+  });
+
+  it('forwards additional props to anchor element', () => {
+    render(
+      <ExternalLink href="https://example.com" data-testid="external-link">
+        Link
+      </ExternalLink>,
+    );
+
+    const link = screen.getByTestId('external-link');
+
+    expect(link).toBeInTheDocument();
+  });
+
+  it('renders with complex children', () => {
+    render(
+      <ExternalLink href="https://example.com">
+        <span>Complex </span>
+
+        <strong>Content</strong>
+      </ExternalLink>,
+    );
+
+    const link = screen.getByRole('link');
+
+    expect(link).toBeInTheDocument();
+    expect(link).toHaveTextContent('Complex Content');
+  });
+
+  it('screen reader text is visually hidden but accessible', () => {
+    render(<ExternalLink href="https://example.com">Link</ExternalLink>);
+
+    const srText = screen.getByText('(opens in new tab)', { exact: false });
+
+    expect(srText).toHaveClass('sr-only');
+  });
+});

package/src/components/link/ExternalLink.tsx

@@ -24,5 +24,6 @@ export const ExternalLink = ({ href, className, children, ...props }: ExternalLi
     target="_blank"
   >
     {children}
+    <span className="sr-only"> (opens in new tab)</span>
   </a>
 );

package/src/http/stream.test.ts

@@ -0,0 +1,98 @@
+import { readJsonXLinesStream } from './stream';
+
+const createMockReader = (chunks: Uint8Array[]) => {
+  let index = 0;
+
+  return {
+    read: vi.fn(async () => {
+      if (index < chunks.length) {
+        return { value: chunks[index++], done: false };
+      }
+
+      return { value: undefined, done: true };
+    }),
+    releaseLock: vi.fn(),
+  };
+};
+
+const createMockResponse = (chunks: string[]): Response => {
+  const encoder = new TextEncoder();
+  const uintChunks = chunks.map((c) => encoder.encode(c));
+
+  const mockReader = createMockReader(uintChunks);
+
+  return {
+    status: 200,
+    body: {
+      getReader: () => mockReader,
+    },
+  } as unknown as Response;
+};
+
+describe('readJsonXLinesStream', () => {
+  it('parses valid NDJSON chunks', async () => {
+    const response = createMockResponse([
+      '{"id":1,"name":"Alice"}\n{"id":2,',
+      '"name":"Bob"}\n{"id":3,"name":"Charlie"}\n',
+    ]);
+
+    const result = await readJsonXLinesStream(response);
+
+    expect(result).toEqual([
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' },
+      { id: 3, name: 'Charlie' },
+    ]);
+  });
+
+  it('ignores invalid JSON lines', async () => {
+    const response = createMockResponse([
+      '{"id":1,"name":"Alice"}\nINVALID_JSON\n{"id":2,"name":"Bob"}\n',
+    ]);
+
+    const result = await readJsonXLinesStream(response);
+
+    expect(result).toEqual([
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' },
+    ]);
+  });
+
+  it('handles trailing line without newline', async () => {
+    const response = createMockResponse(['{"id":1,"name":"Alice"}\n{"id":2,"name":"Bob"}']);
+
+    const result = await readJsonXLinesStream(response);
+
+    expect(result).toEqual([
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' },
+    ]);
+  });
+
+  it('returns empty array when no valid data', async () => {
+    const response = createMockResponse(['\n\n']);
+
+    const result = await readJsonXLinesStream(response);
+
+    expect(result).toEqual([]);
+  });
+
+  it('skips whitespace-only lines', async () => {
+    const response = createMockResponse(['   \n{"id":1,"name":"Alice"}\n  \n']);
+
+    const result = await readJsonXLinesStream(response);
+
+    expect(result).toEqual([{ id: 1, name: 'Alice' }]);
+  });
+
+  it('logs a warning for invalid JSON', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const response = createMockResponse(['INVALID\n']);
+
+    await readJsonXLinesStream(response);
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+
+    warnSpy.mockRestore();
+  });
+});

package/src/map/MapComponent.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useRef, useState } from 'react';
+import { memo, useEffect, useRef, useState } from 'react';
 
 import { Map, Overlay, View } from 'ol';
 import { Attribution, ScaleLine, Zoom } from 'ol/control';
@@ -17,7 +17,6 @@ import type { PopupDirection } from '../types/map';
 export type MapComponentProps = {
   osMapsApiKey?: string;
   basePath: string;
-  isLoading?: boolean;
 };
 
 const positionTransforms: Record<PopupDirection, string> = {
@@ -39,9 +38,12 @@ const arrowStyles: Record<PopupDirection, string> = {
  * and basic controls are added to the map. The map component encapsulates
  * a number of child components, used to interact with the map itself.
  *
+ * Memoized to prevent unnecessary re-renders that could conflict with
+ * OpenLayers' imperative DOM manipulation.
+ *
  * @return {*}
  */
-export const MapComponent = ({ osMapsApiKey, basePath, isLoading }: MapComponentProps) => {
+const MapComponentBase = ({ osMapsApiKey, basePath }: MapComponentProps) => {
   const [popupFeatures, setPopupFeatures] = useState([]);
   const [popupCoordinate, setPopupCoordinate] = useState<number[] | null>(null);
   const [popupPositionClass, setPopupPositionClass] = useState<PopupDirection>('bottom-right');
@@ -155,15 +157,6 @@ export const MapComponent = ({ osMapsApiKey, basePath, isLoading }: MapComponent
         // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
         tabIndex={0}
       >
-        {isLoading ? (
-          <div className="absolute inset-0 flex items-center justify-center bg-white/50 z-10">
-            <div
-              className="w-9 h-9 border-4 border-gray-200 border-t-blue-500 rounded-full
-                animate-spin"
-            />
-          </div>
-        ) : null}
-
         <div
           className={`absolute z-20 ${positionTransforms[popupPositionClass]}`}
           id="popup-container"
@@ -182,3 +175,5 @@ export const MapComponent = ({ osMapsApiKey, basePath, isLoading }: MapComponent
     </div>
   );
 };
+
+export const MapComponent = memo(MapComponentBase);

package/src/map/geocoder/Geocoder.test.tsx

@@ -1,12 +1,11 @@
 import Map from 'ol/Map';
 import View from 'ol/View';
-import { describe, expect, it, vi } from 'vitest';
 
 import { Geocoder } from './Geocoder';
 import { render, screen, userEvent } from '../../test/renderers';
 
 class MockView extends View {
-  animate = vi.fn((options, callback) => {
+  animate = vi.fn((_, callback) => {
     // Immediately execute callback if provided (simulating instant animation)
     if (typeof callback === 'function') {
       callback(true);

package/src/map/geocoder/Geocoder.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useId, useRef, useState } from 'react';
+import { useEffect, useId, useRef, useState } from 'react';
 
 import type Map from 'ol/Map';
 
@@ -129,6 +129,15 @@ export const Geocoder = ({
   const [status, setStatus] = useState('');
   const [isSearching, setIsSearching] = useState(false);
 
+  // Scroll the active result into view when navigating with arrow keys
+  useEffect(() => {
+    if (activeIndex >= 0) {
+      document
+        .getElementById(`${listboxId}-option-${activeIndex}`)
+        ?.scrollIntoView({ block: 'nearest' });
+    }
+  }, [activeIndex, listboxId]);
+
   const performSearch = async () => {
     if (query.length < minChars) {
       setStatus(`Enter at least ${minChars} characters`);

package/src/map/osOpenNamesSearch.ts

@@ -63,21 +63,6 @@ export const createOsOpenNamesSearch = (options: OsOpenNamesSearchOptions) => {
 
     return features
       .map((feature, index): GeocoderResult | null => {
-        if (feature.geometry.type !== 'Point') {
-          console.error('Geometry type is not Point');
-
-          return null;
-        }
-
-        const [lon, lat] = feature.geometry.coordinates;
-
-        // Type guard: ensure coordinates are valid numbers
-        if (typeof lon !== 'number' || typeof lat !== 'number') {
-          console.error('Invalid coordinates: lon or lat is not a number');
-
-          return null;
-        }
-
         const properties = feature.properties ?? {};
 
         // Handle address which can be an object or string
@@ -88,35 +73,60 @@ export const createOsOpenNamesSearch = (options: OsOpenNamesSearchOptions) => {
 
           label = [addr.name, addr.town, addr.country].filter(Boolean).join(', ');
         } else {
-          label = properties.address ?? properties.name ?? `${lat}, ${lon}`;
-        }
-
-        const [x, y] = transform([lon, lat], EPSG_4326, EPSG_3857);
-
-        // Type guard: ensure transformed coordinates are valid numbers
-        if (typeof x !== 'number' || typeof y !== 'number') {
-          console.error('Transform failed: x or y is not a number');
-
-          return null;
+          label = properties.address ?? properties.name ?? `result-${index}`;
         }
 
         const result: GeocoderResult = {
           id: properties.id ?? `result-${index}`,
           label,
           group: properties.type ?? properties.localType,
-          center: [x, y],
           // Assign zoom level based on type, fallback to 14
           zoom: ZOOM_BY_TYPE[properties.type] ?? ZOOM_BY_TYPE[properties.localType] ?? 14,
         };
 
-        // Transform bbox to map projection if available
+        // Prefer bbox — works for all geometry types (Point, Polygon, MultiPolygon)
         if (feature.bbox && Array.isArray(feature.bbox) && feature.bbox.length === 4) {
+          const [minLon, minLat, maxLon, maxLat] = feature.bbox;
+
           result.extent = transformExtent(feature.bbox, EPSG_4326, EPSG_3857) as [
             number,
             number,
             number,
             number,
           ];
+
+          const [x, y] = transform(
+            [(minLon + maxLon) / 2, (minLat + maxLat) / 2],
+            EPSG_4326,
+            EPSG_3857,
+          );
+
+          if (typeof x === 'number' && typeof y === 'number') {
+            result.center = [x, y];
+          }
+        } else if (feature.geometry.type === 'Point') {
+          // Fallback for Point features without a bbox
+          const [lon, lat] = feature.geometry.coordinates;
+
+          if (typeof lon !== 'number' || typeof lat !== 'number') {
+            console.error('Invalid coordinates: lon or lat is not a number');
+
+            return null;
+          }
+
+          const [x, y] = transform([lon, lat], EPSG_4326, EPSG_3857);
+
+          if (typeof x !== 'number' || typeof y !== 'number') {
+            console.error('Transform failed: x or y is not a number');
+
+            return null;
+          }
+
+          result.center = [x, y];
+        } else {
+          console.error('Feature has no bbox and geometry is not a Point');
+
+          return null;
         }
 
         return result;

package/src/types/navigation.ts

@@ -3,6 +3,6 @@ import type { ReactNode } from 'react';
 export type NavLink = {
   label: string;
   url: string;
-  isExternal?: boolean;
+  openInNewTab?: boolean;
   icon?: ReactNode;
 };

package/src/components/InfoBox/hooks/index.ts

@@ -1,3 +0,0 @@
-export { useInfoBoxPosition } from './useInfoBoxPosition';
-export { useInfoBoxState } from './useInfoBoxState';
-export { usePortalMount } from './usePortalMount';