@tpzdsp/next-toolkit 1.15.2 → 2.0.0

package/README.md

@@ -5,7 +5,7 @@ A modern, reusable React component library designed specifically for Next.js app
 ## 📋 Prerequisites
 
 - **Node.js**: 22.17.1 (managed with `asdf`)
-- **Package Manager**: Yarn (preferred) or npm
+- **Package Manager**: pnpm (preferred) or npm
 - **Next.js**: 13+ (peer dependency)
 - **React**: 18+ (peer dependency)
 
@@ -23,11 +23,11 @@ A modern, reusable React component library designed specifically for Next.js app
 ## Installation
 
 ```bash
-yarn add @your-org/nextjs-library
+pnpm add @your-org/nextjs-library
 # or
 npm install @your-org/nextjs-library
 # or
-pnpm add @your-org/nextjs-library
+yarn add @your-org/nextjs-library
 ```
 
 ## Usage
@@ -239,25 +239,25 @@ This library distributes **raw TypeScript/TSX files** instead of compiled bundle
 
 ```bash
 # Install dependencies
-yarn install
+pnpm install
 
 # Start development server
-yarn dev
+pnpm dev
 
 # Run tests
-yarn test
+pnpm test
 
 # Run tests with UI
-yarn test:ui
+pnpm test:ui
 
 # Build the library (TypeScript check only)
-yarn build
+pnpm build
 
 # Build distribution files (if needed)
-yarn build:dist
+pnpm build:dist
 
 # Preview the built library
-yarn preview
+pnpm preview
 ```
 
 ## Local Development with Yalc
@@ -285,7 +285,7 @@ yalc publish
 yalc add @tpzdsp/next-toolkit
 
 # Install dependencies
-yarn install
+pnpm install
 ```
 
 ### Your Next.js App Configuration
@@ -313,7 +313,7 @@ module.exports = nextConfig;
 yalc push
 
 # 3. In your test app, clear Next.js cache and restart
-rm -rf .next && yarn dev
+rm -rf .next && pnpm dev
 ```
 
 ### Why No Hot Reloading?
@@ -327,7 +327,7 @@ rm -rf .next && yarn dev
 ```bash
 # In your Next.js app directory
 yalc remove @tpzdsp/next-toolkit
-yarn install
+pnpm install
 ```
 
 ### Benefits Despite Manual Process
@@ -464,13 +464,13 @@ This library uses Vitest and React Testing Library for testing:
 
 ```bash
 # Run all tests
-yarn test
+pnpm test
 
 # Run tests in watch mode
-yarn test:watch
+pnpm test:watch
 
 # Run tests with coverage
-yarn test:coverage
+pnpm test:coverage
 ```
 
 ## Build Configuration
@@ -543,12 +543,12 @@ import '@your-org/nextjs-library/src/assets/styles/globals.css';
 2. **Install dependencies:**
 
    ```bash
-   yarn install
+   pnpm install
    ```
 
 3. **Run tests to ensure everything works:**
    ```bash
-   yarn test
+   pnpm test
    ```
 
 ### Development Workflow
@@ -557,7 +557,7 @@ import '@your-org/nextjs-library/src/assets/styles/globals.css';
 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
 3. Make your changes following our component templates above
 4. Add tests for your changes (`src/test/YourComponent.test.tsx`)
-5. Run the test suite (`yarn test`)
+5. Run the test suite (`pnpm test`)
 6. Test with yalc in a real Next.js app
 7. Commit your changes (`git commit -m 'Add some amazing feature'`)
 8. Push to the branch (`git push origin feature/amazing-feature`)

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@tpzdsp/next-toolkit",
-  "version": "1.15.2",
+  "version": "2.0.0",
   "description": "A reusable React component library for Next.js applications",
   "engines": {
-    "node": ">= 24.12.0",
-    "yarn": ">=1.22.22"
+    "node": "^24.12.0",
+    "pnpm": "^10.0.0"
   },
   "type": "module",
   "private": false,
@@ -121,67 +121,50 @@
     "dev:push": "yalc push",
     "tsc:check": "tsc -b --noEmit",
     "storybook": "storybook dev -p 6006",
-    "release": "semantic-release"
+    "release": "semantic-release",
+    "postinstall": "if [ \"$CI\" != \"true\" ]; then ./postinstall.sh; fi"
   },
   "devDependencies": {
     "@better-fetch/fetch": "^1.1.21",
-    "@eslint/js": "^9.30.1",
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^12.0.2",
-    "@storybook/addon-docs": "10.2.0",
-    "@storybook/addon-links": "10.2.0",
-    "@storybook/addon-onboarding": "10.2.0",
-    "@storybook/react-vite": "10.2.0",
+    "@floating-ui/react": "^0.27.17",
+    "@storybook/addon-docs": "10.3.5",
+    "@storybook/addon-links": "10.3.5",
+    "@storybook/addon-onboarding": "10.3.5",
+    "@storybook/react-vite": "10.3.5",
     "@tailwindcss/typography": "^0.5.16",
     "@tanstack/react-query": "^5.90.19",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.6.4",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
-    "@tpzdsp/eslint-config-dsp": "^2.0.0",
+    "@tpzdsp/eslint-config-dsp": "^4.0.0",
     "@turf/turf": "^7.2.0",
     "@types/geojson": "^7946.0.16",
     "@types/jsonwebtoken": "^9.0.10",
-    "@types/node": "^24.10.9",
+    "@types/node": "^24.12.2",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
-    "@typescript-eslint/eslint-plugin": "^8.38.0",
-    "@typescript-eslint/parser": "^8.38.0",
-    "@vitejs/plugin-react": "^5.1.2",
+    "@vitejs/plugin-react": "^6.0.1",
     "@vitest/coverage-v8": "^4.0.17",
     "@vitest/eslint-plugin": "^1.3.4",
     "autoprefixer": "^10.4.21",
     "buffer": "^6.0.3",
     "crypto-browserify": "^3.12.1",
     "date-fns": "^4.1.0",
-    "eslint": "^9.30.1",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-import-resolver-alias": "^1.1.2",
-    "eslint-import-resolver-typescript": "^4.4.4",
-    "eslint-plugin-import-x": "^4.16.1",
-    "eslint-plugin-jest-dom": "^5.5.0",
-    "eslint-plugin-jsx-a11y": "^6.10.2",
-    "eslint-plugin-prettier": "^5.5.5",
-    "eslint-plugin-react": "^7.37.5",
-    "eslint-plugin-react-hooks": "^7.0.1",
-    "eslint-plugin-react-refresh": "^0.4.20",
-    "eslint-plugin-sonarjs": "^3.0.5",
-    "eslint-plugin-storybook": "10.2.0",
-    "focus-trap": "^7.6.5",
-    "focus-trap-react": "^11.0.6",
+    "eslint": "^9.39.4",
+    "eslint-plugin-storybook": "10.3.5",
+    "focus-trap": "^8.0.1",
+    "focus-trap-react": "^12.0.0",
     "geojson": "^0.5.0",
     "globals": "^17.0.0",
     "husky": "^9.1.7",
-    "jsdom": "^27.4.0",
+    "jsdom": "^29.0.2",
     "jsonwebtoken": "^9.0.3",
     "next": "^16.1.4",
     "ol": "^10.6.1",
     "ol-mapbox-style": "^13.0.1",
     "postcss": "^8.5.6",
     "prettier": "^3.8.1",
-    "prettier-plugin-classnames": "^0.9.0",
-    "prettier-plugin-tailwindcss": "^0.7.2",
     "process": "^0.11.10",
     "proj4": "^2.19.10",
     "react": "^19.2.1",
@@ -192,58 +175,50 @@
     "react-select-event": "^5.5.1",
     "rollup-plugin-peer-deps-external": "^2.2.4",
     "semantic-release": "^25.0.2",
-    "storybook": "10.2.0",
+    "storybook": "10.3.5",
     "stream-browserify": "^3.0.0",
     "tailwind-merge": "^3.4.0",
     "tailwindcss": "^3.4.16",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.2",
     "typescript-eslint": "^8.35.1",
     "util": "^0.12.5",
-    "vite": "^7.0.4",
+    "vite": "^8.0.8",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^4.0.17",
     "zod": "^4.3.5"
   },
   "peerDependencies": {
-    "@better-fetch/fetch": "^1.1.21",
-    "@floating-ui/react": "^0.27.17",
-    "@tanstack/react-query": "^5.90.19",
-    "@testing-library/react": "^16.0.0",
-    "@testing-library/user-event": "^14.6.1",
-    "@turf/turf": "^7.2.0",
-    "@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.6",
-    "geojson": "^0.5.0",
-    "next": "^16.1.4",
-    "ol": "^10.6.1",
-    "ol-mapbox-style": "^13.0.1",
-    "proj4": "^2.19.10",
-    "react": "^19.2.1",
-    "react-dom": "^19.2.1",
-    "react-error-boundary": "^6.0.0",
-    "react-icons": "^5.5.0",
-    "zod": "^4.3.5"
+    "@better-fetch/fetch": "^1",
+    "@floating-ui/react": "^0.27",
+    "@tanstack/react-query": "^5",
+    "@turf/turf": "^7",
+    "date-fns": "^4",
+    "focus-trap": "^8",
+    "focus-trap-react": "^12",
+    "geojson": "^0.5",
+    "jsonwebtoken": "^9",
+    "next": "^16",
+    "ol": "^10",
+    "ol-mapbox-style": "^13",
+    "proj4": "^2",
+    "react": "^19",
+    "react-dom": "^19",
+    "react-error-boundary": "^6",
+    "react-icons": "^5",
+    "react-select": "^5",
+    "zod": "^4"
   },
   "peerDependenciesMeta": {
-    "@tanstack/react-query": {
-      "optional": true
-    },
     "@better-fetch/fetch": {
       "optional": true
     },
     "@floating-ui/react": {
       "optional": true
     },
-    "@turf/turf": {
-      "optional": true
-    },
-    "@types/geojson": {
+    "@tanstack/react-query": {
       "optional": true
     },
-    "@types/jsonwebtoken": {
+    "@turf/turf": {
       "optional": true
     },
     "date-fns": {
@@ -277,13 +252,7 @@
       "optional": true
     }
   },
-  "optionalDependencies": {
-    "react-select": "^5.10.2"
-  },
   "release": {
     "extends": "./release.config.js"
-  },
-  "dependencies": {
-    "@floating-ui/react": "^0.27.17"
   }
 }

package/src/components/InfoBox/InfoBox.tsx

@@ -134,7 +134,7 @@ export const InfoBox = ({
         <Icon className={iconClasses} aria-hidden="true" />
       </button>
 
-      {isOpen && (
+      {isOpen ? (
         <FloatingPortal>
           <FloatingFocusManager context={context} modal={false}>
             <div
@@ -165,7 +165,7 @@ export const InfoBox = ({
             </div>
           </FloatingFocusManager>
         </FloatingPortal>
-      )}
+      ) : null}
     </div>
   );
 };

package/src/components/SlidingPanel/SlidingPanel.tsx

@@ -1,6 +1,14 @@
 'use client';
 
-import { useState, useEffect, type ReactNode, useRef, useMemo, useId } from 'react';
+import {
+  useState,
+  useEffect,
+  type ReactNode,
+  useRef,
+  useMemo,
+  useId,
+  type CSSProperties,
+} from 'react';
 
 import { FocusTrap } from 'focus-trap-react';
 
@@ -115,7 +123,7 @@ export const SlidingPanel = ({
   }[position];
 
   // Dynamic positioning using actual panel dimensions
-  const getButtonStyle = useMemo(() => {
+  const getButtonStyle = useMemo((): CSSProperties => {
     if (position === 'center-left') {
       return {
         left: isVisible ? `${panelDimensions.width}px` : '0px',
@@ -188,7 +196,7 @@ export const SlidingPanel = ({
 
             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;

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

@@ -310,14 +310,14 @@ export const LongPageExample: Story = {
                 fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa
                 qui officia deserunt mollit anim id est laborum.
               </p>
-              {i % 10 === 9 && (
+              {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>
-              )}
+              ) : null}
             </article>
           ))}
         </section>

package/src/components/backToTop/BackToTop.tsx

@@ -102,7 +102,7 @@ export const BackToTop = ({
   );
 
   if (!isVisible) {
-    return null;
+    return <></>;
   }
 
   return (

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

@@ -26,7 +26,7 @@ export const HeaderAuthClient = ({ hostname, credentials }: HeaderAuthClientProp
         <span>Welcome,</span> {credentials ? credentials.user.email : 'Guest'}
       </span>
 
-      {isClient && (
+      {isClient ? (
         <Link
           href={`${hostname}/${credentials ? 'api/logout' : 'login'}?redirect-uri=${encodeURIComponent(window.location.href)}`}
           className="text-white visited:text-white active:text-black hover:text-white"
@@ -34,7 +34,7 @@ export const HeaderAuthClient = ({ hostname, credentials }: HeaderAuthClientProp
         >
           <span className="text-base">{credentials ? 'Logout' : 'Login'}</span>
         </Link>
-      )}
+      ) : null}
     </span>
   );
 };

package/src/http/constants.ts

@@ -20,18 +20,21 @@ export const MimeType = {
  */
 export type MimeTypes = (typeof MimeType)[keyof typeof MimeType];
 
+const jsonMimeTypes = [MimeType.Json, MimeType.GeoJson, MimeType.JsonLd] as const;
+const textMimeTypes = [MimeType.Text, MimeType.Csv] as const;
+
 /**
  * Returns `true` if the mime type is a non-streamed JSON mime type (I.E. not JSON X-Lines).
  */
 export const isJsonMimeType = (mime: MimeTypes | string | null): boolean => {
-  return ([MimeType.Json, MimeType.GeoJson, MimeType.JsonLd] as string[]).includes(mime ?? '');
+  return mime != null && jsonMimeTypes.includes(mime as (typeof jsonMimeTypes)[number]);
 };
 
 /**
  * Returns `true` if the mime type is a plain-text mime type.
  */
 export const isTextMimeType = (mime: MimeTypes | string | null): boolean => {
-  return ([MimeType.Text, MimeType.Csv] as string[]).includes(mime ?? '');
+  return mime != null && textMimeTypes.includes(mime as (typeof textMimeTypes)[number]);
 };
 
 /**
@@ -52,6 +55,8 @@ export const HttpStatus = {
   InternalServerError: 500,
   NotImplemented: 501,
   BadGateway: 502,
+  ServiceUnavailable: 503,
+  GatewayTimeout: 504,
 } as const;
 
 /**

package/src/http/logger.ts

@@ -7,7 +7,7 @@ const MAX_PREVIEW_LENGTH = 150;
 // Tries to print data as a string.
 const stringify = (data: unknown): string | null => {
   if (data == null) {
-    return null;
+    return '';
   }
 
   try {
@@ -22,7 +22,7 @@ const preview = (data: unknown): string | null => {
   const str = stringify(data);
 
   if (str == null) {
-    return null;
+    return '';
   }
 
   if (str.length > MAX_PREVIEW_LENGTH) {
@@ -36,7 +36,7 @@ type RequestMeta = {
   requestId: string;
 };
 
-type RequestLoggerMessageExtras = {
+export type RequestLoggerMessageExtras = {
   loggerOverrides?: {
     requestFormat?: (args: { request: MetaContext }) => string;
 
@@ -191,7 +191,7 @@ const formatBodyLine = ({
   const rendered = truncateBody ? preview(body) : stringify(body);
 
   if (!rendered) {
-    return null;
+    return '';
   }
 
   return truncateBody ? `\t↳ ${label}: ${rendered}` : `\t↳ ${label}:\n${rendered}`;

package/src/map/LayerSwitcherPanel.tsx

@@ -48,7 +48,7 @@ export const LayerSwitcherPanel = ({
   }, [isOpen]);
 
   if (!isMounted || !isOpen) {
-    return null;
+    return <></>;
   }
 
   // Calculate position based on button position

package/src/map/MapComponent.tsx

@@ -135,26 +135,21 @@ const MapComponentBase = ({ osMapsApiKey, basePath, children }: MapComponentProp
           return true; // stop iteration
         }
 
-        // Direct feature (e.g. polygon) — only show popup for the sampling points
-        // layer, not boundary or AOI layers which may also have name properties.
+        // Direct feature (e.g. polygon or MVT tile feature) — only show popup
+        // for the sampling points layer, not boundary or AOI layers.
         if (layerName !== LAYER_NAMES.SamplingPoints) {
           return;
         }
 
-        const name = feature.get('name');
-        const notation = feature.get('notation');
+        const coordinate = event.coordinate;
+        const direction = getPopupPositionClass(coordinate, newMap);
 
-        if (name || notation) {
-          const coordinate = event.coordinate;
-          const direction = getPopupPositionClass(coordinate, newMap);
-
-          setPopupFeatures([feature as Feature]);
-          setPopupCoordinate(coordinate);
-          setPopupPositionClass(direction);
-          overlay.setPosition(event.coordinate);
+        setPopupFeatures([feature as Feature]);
+        setPopupCoordinate(coordinate);
+        setPopupPositionClass(direction);
+        overlay.setPosition(event.coordinate);
 
-          return true; // stop iteration
-        }
+        return true; // stop iteration
       });
     });
 

package/src/map/Popup.tsx

@@ -18,7 +18,7 @@ export const Popup = ({
   arrowClasses = 'bottom-left',
 }: PopupProps) => {
   if (!clickedCoord) {
-    return null;
+    return <></>;
   }
 
   return (

package/src/map/geocoder/Geocoder.tsx

@@ -1,11 +1,12 @@
 'use client';
 
-import { useEffect, useId, useRef, useState } from 'react';
+import { useCallback, useEffect, useId, useRef, useState } from 'react';
 
 import type Map from 'ol/Map';
 
 import { groupResults } from './groupResults';
 import type { GeocoderResult } from './types';
+import { useDebounce } from '../../hooks/useDebounce';
 
 // SVG Icons matching Mapbox GL Geocoder style
 const SearchIcon = () => (
@@ -69,6 +70,9 @@ const LoadingIcon = () => (
   </svg>
 );
 
+// Typeahead defaults
+const DEFAULT_TYPEAHEAD_DELAY_MS = 500;
+
 // Animation defaults - can be overridden via props
 const DEFAULT_TARGET_ZOOM = 14;
 const DEFAULT_FLY_OUT_ZOOM_MIN = 6;
@@ -97,8 +101,10 @@ export type GeocoderProps = {
   fitPadding?: number;
   /** Debug callback for logging results and selections */
   onDebug?: (event: { type: 'results' | 'select' | 'clear'; data?: unknown }) => void;
-  // To enable auto-search on typing (debounced), import useDebounce from '../../hooks/useDebounce'
-  // and add: debounceDelay?: number; prop, then use debouncedQuery in a useEffect
+  /** Enable typeahead search while typing */
+  enableTypeahead?: boolean;
+  /** Debounce delay in ms for typeahead search (default: 500) */
+  typeaheadDelay?: number;
 };
 
 export const Geocoder = ({
@@ -114,6 +120,8 @@ export const Geocoder = ({
   flyToDuration = DEFAULT_FLY_TO_DURATION,
   fitPadding = DEFAULT_FIT_PADDING,
   onDebug,
+  enableTypeahead = false,
+  typeaheadDelay = DEFAULT_TYPEAHEAD_DELAY_MS,
 }: GeocoderProps) => {
   const generatedId = useId();
   const id = providedId ?? generatedId;
@@ -129,6 +137,50 @@ export const Geocoder = ({
   const [status, setStatus] = useState('');
   const [isSearching, setIsSearching] = useState(false);
 
+  const debouncedQuery = useDebounce(query, typeaheadDelay);
+
+  const performSearch = useCallback(
+    async (queryStr: string) => {
+      if (queryStr.length < minChars) {
+        setStatus(`Enter at least ${minChars} characters`);
+
+        return;
+      }
+
+      setIsSearching(true);
+      setStatus('Searching...');
+
+      try {
+        const data = await search(queryStr);
+
+        setResults(data);
+        setSelectedId(null);
+        setOpen(true);
+        setActiveIndex(-1);
+        setStatus(data.length ? `${data.length} results available` : 'No results found');
+
+        // Debug callback for results
+        onDebug?.({
+          type: 'results',
+          data: { query: queryStr, results: data, count: data.length },
+        });
+      } catch (error) {
+        console.error('Search error:', error);
+        setStatus('There was an error reaching the server');
+        setResults([]);
+      } finally {
+        setIsSearching(false);
+      }
+    },
+    [minChars, search, onDebug],
+  );
+
+  useEffect(() => {
+    if (enableTypeahead && debouncedQuery.length >= minChars) {
+      performSearch(debouncedQuery);
+    }
+  }, [debouncedQuery, enableTypeahead, minChars, performSearch]);
+
   // Scroll the active result into view when navigating with arrow keys
   useEffect(() => {
     if (activeIndex >= 0) {
@@ -138,36 +190,6 @@ export const Geocoder = ({
     }
   }, [activeIndex, listboxId]);
 
-  const performSearch = async () => {
-    if (query.length < minChars) {
-      setStatus(`Enter at least ${minChars} characters`);
-
-      return;
-    }
-
-    setIsSearching(true);
-    setStatus('Searching...');
-
-    try {
-      const data = await search(query);
-
-      setResults(data);
-      setSelectedId(null);
-      setOpen(true);
-      setActiveIndex(-1);
-      setStatus(data.length ? `${data.length} results available` : 'No results found');
-
-      // Debug callback for results
-      onDebug?.({ type: 'results', data: { query, results: data, count: data.length } });
-    } catch (error) {
-      console.error('Search error:', error);
-      setStatus('There was an error reaching the server');
-      setResults([]);
-    } finally {
-      setIsSearching(false);
-    }
-  };
-
   const selectResult = (result: GeocoderResult) => {
     const view = map.getView();
     const currentZoom = view.getZoom() ?? 10;
@@ -257,7 +279,10 @@ export const Geocoder = ({
       </label>
 
       {/* Mapbox-style geocoder container */}
-      <div className="relative bg-white rounded shadow-lg transition-all duration-200">
+      <div
+        className="relative bg-white rounded shadow-lg transition-all duration-200
+          focus-within:ring-2 focus-within:ring-focus"
+      >
         <SearchIcon />
 
         <input
@@ -298,7 +323,7 @@ export const Geocoder = ({
               if (activeResult && open) {
                 selectResult(activeResult);
               } else {
-                performSearch();
+                performSearch(query);
               }
             }
 
@@ -335,7 +360,7 @@ export const Geocoder = ({
               );
             }
 
-            return null;
+            return <></>;
           })()}
         </div>
       </div>
@@ -392,7 +417,7 @@ export const Geocoder = ({
                 );
               }
 
-              return null;
+              return <></>;
             })()
           )}
         </div>

package/src/map/osOpenNamesSearch.test.tsx

@@ -0,0 +1,186 @@
+import { transform, transformExtent } from 'ol/proj';
+import { describe, expect, it, vi, afterEach } from 'vitest';
+
+import {
+  mapOsOpenNamesFeaturesToGeocoderResults,
+  mapOsOpenNamesFeatureToGeocoderResult,
+} from './osOpenNamesSearch';
+
+vi.mock('ol/proj', () => ({
+  transform: vi.fn((coords) => coords),
+  transformExtent: vi.fn((extent) => extent),
+}));
+
+const createPointFeature = (overrides: Record<string, unknown> = {}) =>
+  ({
+    type: 'Feature',
+    properties: {
+      id: 'place-1',
+      address: '10 Downing Street',
+      type: 'populatedPlace',
+    },
+    geometry: {
+      type: 'Point',
+      coordinates: [-0.1276, 51.5034],
+    },
+    ...overrides,
+  }) as never;
+
+const createPolygonFeature = (overrides: Record<string, unknown> = {}) =>
+  ({
+    type: 'Feature',
+    properties: {
+      id: 'area-1',
+      name: 'Westminster',
+      type: 'city',
+    },
+    geometry: {
+      type: 'Polygon',
+      coordinates: [],
+    },
+    bbox: [-0.15, 51.49, -0.12, 51.52],
+    ...overrides,
+  }) as never;
+
+describe('mapOsOpenNamesFeatureToGeocoderResult', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('maps a Point feature with string address', () => {
+    const result = mapOsOpenNamesFeatureToGeocoderResult(createPointFeature(), 0);
+
+    expect(result[0]).toEqual({
+      id: 'place-1',
+      label: '10 Downing Street',
+      group: 'populatedPlace',
+      zoom: expect.any(Number),
+      center: [-0.1276, 51.5034],
+    });
+
+    expect(transform).toHaveBeenCalledWith(
+      [-0.1276, 51.5034],
+      expect.anything(),
+      expect.anything(),
+    );
+  });
+
+  it('builds the label from address object fields', () => {
+    const feature = createPointFeature({
+      properties: {
+        id: 'place-2',
+        address: {
+          name: 'Baker Street',
+          town: 'London',
+          country: 'England',
+        },
+        type: 'street',
+      },
+    });
+
+    const result = mapOsOpenNamesFeatureToGeocoderResult(feature, 1);
+
+    expect(result[0]?.label).toBe('Baker Street, London, England');
+  });
+
+  it('uses bbox to populate extent and center', () => {
+    const result = mapOsOpenNamesFeatureToGeocoderResult(createPolygonFeature(), 0);
+
+    expect(result[0]).toEqual({
+      id: 'area-1',
+      label: 'Westminster',
+      group: 'city',
+      zoom: expect.any(Number),
+      extent: [-0.15, 51.49, -0.12, 51.52],
+      center: [-0.135, 51.505],
+    });
+
+    expect(transformExtent).toHaveBeenCalledWith(
+      [-0.15, 51.49, -0.12, 51.52],
+      expect.anything(),
+      expect.anything(),
+    );
+
+    expect(transform).toHaveBeenCalledWith([-0.135, 51.505], expect.anything(), expect.anything());
+  });
+
+  it('falls back to localType when type is missing', () => {
+    const feature = createPointFeature({
+      properties: {
+        id: 'place-3',
+        name: 'Somewhere',
+        localType: 'Village',
+      },
+    });
+
+    const result = mapOsOpenNamesFeatureToGeocoderResult(feature, 0);
+
+    expect(result[0]?.group).toBe('Village');
+  });
+
+  it('falls back to generated id and label when missing', () => {
+    const feature = createPointFeature({
+      properties: {},
+    });
+
+    const result = mapOsOpenNamesFeatureToGeocoderResult(feature, 7);
+
+    expect(result[0]?.id).toBe('result-7');
+    expect(result[0]?.label).toBe('result-7');
+  });
+
+  it('returns null for non-Point geometry without bbox', () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    const feature = createPolygonFeature({
+      bbox: undefined,
+    });
+
+    const result = mapOsOpenNamesFeatureToGeocoderResult(feature, 0);
+
+    expect(result[0]).toBeUndefined();
+    expect(errorSpy).toHaveBeenCalledWith('Feature has no bbox and geometry is not a Point');
+  });
+
+  it('returns null for invalid Point coordinates', () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    const feature = createPointFeature({
+      geometry: {
+        type: 'Point',
+        coordinates: ['bad', 51.5],
+      },
+    });
+
+    const result = mapOsOpenNamesFeatureToGeocoderResult(feature, 0);
+
+    expect(result[0]).toBeUndefined();
+    expect(errorSpy).toHaveBeenCalledWith('Invalid coordinates: lon or lat is not a number');
+  });
+});
+
+describe('mapOsOpenNamesFeaturesToGeocoderResults', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('maps features and filters out null results', () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    const results = mapOsOpenNamesFeaturesToGeocoderResults([
+      createPointFeature({
+        properties: { id: 'valid-1', address: 'Valid place', type: 'street' },
+      }),
+      createPolygonFeature({
+        bbox: undefined,
+      }),
+      createPointFeature({
+        properties: { id: 'valid-2', address: 'Another place', type: 'street' },
+      }),
+    ]);
+
+    expect(results).toHaveLength(2);
+    expect(results.map((result) => result.id)).toEqual(['valid-1', 'valid-2']);
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/map/osOpenNamesSearch.ts

@@ -1,4 +1,4 @@
-import type { FeatureCollection } from 'geojson';
+import type { Feature, FeatureCollection } from 'geojson';
 import { transform, transformExtent } from 'ol/proj';
 
 import type { GeocoderResult } from './geocoder/types';
@@ -26,6 +26,82 @@ const ZOOM_BY_TYPE: Record<string, number> = {
   'Postcode Unit': 18,
 };
 
+export const mapOsOpenNamesFeatureToGeocoderResult = (
+  feature: Feature,
+  index: number,
+): [] | [GeocoderResult] => {
+  const properties = feature.properties ?? {};
+
+  let label: string;
+
+  if (properties.address && typeof properties.address === 'object') {
+    const addr = properties.address as { name?: string; town?: string; country?: string };
+
+    label = [addr.name, addr.town, addr.country].filter(Boolean).join(', ');
+  } else {
+    label = properties.address ?? properties.name ?? `result-${index}`;
+  }
+
+  const result: GeocoderResult = {
+    id: properties.id ?? `result-${index}`,
+    label,
+    group: properties.type ?? properties.localType,
+    zoom: ZOOM_BY_TYPE[properties.type] ?? ZOOM_BY_TYPE[properties.localType] ?? 14,
+  };
+
+  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') {
+      console.error('Transform failed: x or y is not a number');
+
+      return [];
+    }
+
+    result.center = [x, y];
+
+    return [result];
+  }
+
+  if (feature.geometry.type === 'Point') {
+    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 [];
+    }
+
+    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 [];
+    }
+
+    result.center = [x, y];
+
+    return [result];
+  }
+
+  console.error('Feature has no bbox and geometry is not a Point');
+
+  return [];
+};
+
+export const mapOsOpenNamesFeaturesToGeocoderResults = (features: Feature[]): GeocoderResult[] =>
+  features.flatMap((feature, index) => mapOsOpenNamesFeatureToGeocoderResult(feature, index));
+
 /**
  * Creates a search function for OS Open Names API that returns GeocoderResult[].
  *
@@ -61,76 +137,6 @@ export const createOsOpenNamesSearch = (options: OsOpenNamesSearchOptions) => {
       return [];
     }
 
-    return features
-      .map((feature, index): GeocoderResult | null => {
-        const properties = feature.properties ?? {};
-
-        // Handle address which can be an object or string
-        let label: string;
-
-        if (properties.address && typeof properties.address === 'object') {
-          const addr = properties.address as { name?: string; town?: string; country?: string };
-
-          label = [addr.name, addr.town, addr.country].filter(Boolean).join(', ');
-        } else {
-          label = properties.address ?? properties.name ?? `result-${index}`;
-        }
-
-        const result: GeocoderResult = {
-          id: properties.id ?? `result-${index}`,
-          label,
-          group: properties.type ?? properties.localType,
-          // Assign zoom level based on type, fallback to 14
-          zoom: ZOOM_BY_TYPE[properties.type] ?? ZOOM_BY_TYPE[properties.localType] ?? 14,
-        };
-
-        // 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;
-      })
-      .filter((result): result is GeocoderResult => result !== null);
+    return mapOsOpenNamesFeaturesToGeocoderResults(features);
   };
 };

package/src/utils/http.ts

@@ -48,7 +48,7 @@ const encodeBase64 = (input: string): string => {
   throw new Error('Base64 encoding not available in this environment');
 };
 
-const getAuthorizationHeader = (): { Authorization: string } | Record<string, never> => {
+const getAuthorizationHeader = (): { Authorization: string } => {
   const apiHasAuth = getNodeEnvVar('API_HAS_AUTH');
   const apiUsername = getNodeEnvVar('API_USERNAME');
   const apiPassword = getNodeEnvVar('API_PASSWORD');
@@ -61,7 +61,7 @@ const getAuthorizationHeader = (): { Authorization: string } | Record<string, ne
     };
   }
 
-  return {};
+  return { Authorization: '' };
 };
 
 // common fetch wrapper to provide auth headers if necessary