@tpzdsp/next-toolkit 2.5.1 → 3.1.0

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

@@ -27,10 +27,9 @@ describe('Geocoder', () => {
     const input = screen.getByRole('combobox');
     const user = userEvent.setup();
 
-    // Type into the input
+    // Typing alone triggers the debounced search, Enter here is just
+    // incidental (it's a no-op with no option focused yet)
     await user.type(input, 'Lon');
-
-    // Press Enter to trigger search
     await user.keyboard('{Enter}');
 
     // Wait for the result to appear
@@ -111,4 +110,48 @@ describe('Geocoder', () => {
     expect(screen.queryByText('London')).not.toBeInTheDocument();
     expect(input).toHaveValue('');
   });
+
+  it('searches automatically after the debounce delay, without pressing Enter', async () => {
+    const search = vi.fn().mockResolvedValue([{ id: '1', label: 'London', center: [0, 0] }]);
+
+    render(<Geocoder map={mockMap} search={search} typeaheadDelay={10} />);
+
+    const input = screen.getByRole('combobox');
+    const user = userEvent.setup();
+
+    await user.type(input, 'Lon');
+
+    const option = await screen.findByText('London');
+
+    expect(option).toBeInTheDocument();
+    expect(search).toHaveBeenCalledWith('Lon');
+  });
+
+  it('selects a result, then clears it with Backspace', async () => {
+    const search = vi.fn().mockResolvedValue([{ id: '1', label: 'London', center: [0, 0] }]);
+
+    render(<Geocoder map={mockMap} search={search} typeaheadDelay={10} />);
+
+    const input = screen.getByRole('combobox');
+    const user = userEvent.setup();
+
+    await user.type(input, 'Lon');
+
+    const option = await screen.findByText('London');
+
+    await user.click(option);
+
+    // Selecting shows the result's label in the control (react-select's
+    // standard single-select behaviour), the same as any other Select in
+    // this library, rather than leaving the raw typed query behind.
+    expect(screen.getByText('London')).toBeInTheDocument();
+
+    // The visible clear (x) button itself is aria-hidden, react-select's own
+    // default, mouse/touch-only, the accessible equivalent is Backspace on
+    // an empty, focused control.
+    await user.click(input);
+    await user.keyboard('{Backspace}');
+
+    expect(screen.queryByText('London')).not.toBeInTheDocument();
+  });
 });

package/src/map/geocoder/Geocoder.tsx

@@ -3,12 +3,13 @@
 import { useCallback, useEffect, useId, useRef, useState } from 'react';
 
 import type Map from 'ol/Map';
-import { ImSpinner2 } from 'react-icons/im';
-import { IoClose, IoSearch } from 'react-icons/io5';
+import { LuLoaderCircle, LuSearch } from 'react-icons/lu';
+import type { GroupBase, OptionsOrGroups } from 'react-select';
 
 import { groupResults } from './groupResults';
 import type { GeocoderResult } from './types';
-import { useDebounce } from '../../hooks/useDebounce';
+import { InputGroup, InputPrefix, InputSwatch } from '../../components/InputGroup/InputGroup';
+import { AsyncSelect } from '../../components/Select/AsyncSelect';
 
 // Typeahead defaults
 const DEFAULT_TYPEAHEAD_DELAY_MS = 500;
@@ -21,6 +22,8 @@ const DEFAULT_ZOOM_OUT_DURATION = 800;
 const DEFAULT_FLY_TO_DURATION = 1500;
 const DEFAULT_FIT_PADDING = 40;
 
+type GeocoderGroup = GroupBase<GeocoderResult>;
+
 export type GeocoderProps = {
   map: Map;
   search: (query: string) => Promise<GeocoderResult[]>;
@@ -41,9 +44,7 @@ export type GeocoderProps = {
   fitPadding?: number;
   /** Debug callback for logging results and selections */
   onDebug?: (event: { type: 'results' | 'select' | 'clear'; data?: unknown }) => void;
-  /** Enable typeahead search while typing */
-  enableTypeahead?: boolean;
-  /** Debounce delay in ms for typeahead search (default: 500) */
+  /** Debounce delay in ms before searching once the user stops typing (default: 500) */
   typeaheadDelay?: number;
 };
 
@@ -60,302 +61,178 @@ 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;
-  const listboxId = `${id}-listbox`;
-
-  const inputRef = useRef<HTMLInputElement>(null);
-
-  const [query, setQuery] = useState('');
-  const [results, setResults] = useState<GeocoderResult[]>([]);
-  const [selectedId, setSelectedId] = useState<string | null>(null);
-  const [activeIndex, setActiveIndex] = useState(-1);
-  const [open, setOpen] = useState(false);
-  const [status, setStatus] = useState('');
+  const inputId = providedId ?? generatedId;
+
+  // Controlled rather than left uncontrolled: shows the selected result's
+  // label in the control (standard single-select behaviour, and the only
+  // way react-select's own clear button appears at all, it's tied to
+  // hasValue, not to whether there's typed input text) and lets clearing
+  // reset it back to null.
+  const [value, setValue] = useState<GeocoderResult | null>(null);
+
+  // Swaps the InputPrefix icon between search and spinner instead of using
+  // react-select's own indicators area (hidden via hideLoadingIndicator
+  // below), which otherwise grows/shrinks as the indicator mounts and
+  // unmounts and shifts the typed text.
   const [isSearching, setIsSearching] = useState(false);
 
-  const debouncedQuery = useDebounce(query, typeaheadDelay);
+  // react-select's own useAsync doesn't debounce loadOptions itself, it
+  // fires on every keystroke, so the delay is implemented here instead.
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  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);
+  useEffect(
+    () => () => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
       }
     },
-    [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) {
-      document
-        .getElementById(`${listboxId}-option-${activeIndex}`)
-        ?.scrollIntoView({ block: 'nearest' });
-    }
-  }, [activeIndex, listboxId]);
-
-  const selectResult = (result: GeocoderResult) => {
-    const view = map.getView();
-    const currentZoom = view.getZoom() ?? 10;
-    const shouldZoomOut = currentZoom > flyOutThreshold;
-    const flyZoom = shouldZoomOut ? Math.max(currentZoom - 4, flyOutZoomMin) : currentZoom;
-    const padding = [fitPadding, fitPadding, fitPadding, fitPadding] as [
-      number,
-      number,
-      number,
-      number,
-    ];
-    // Use result-specific zoom if provided, otherwise fall back to targetZoom prop
-    const finalZoom = result.zoom ?? targetZoom;
-
-    if (result.extent) {
-      if (shouldZoomOut) {
-        // Step 1: Zoom out, then fit to extent (combined pan + zoom)
-        view.animate({ zoom: flyZoom, duration: zoomOutDuration }, () => {
-          view.fit(result.extent!, { padding, duration: flyToDuration });
-        });
-      } else {
-        view.fit(result.extent, { padding, duration: flyToDuration });
-      }
-    } else if (result.center) {
-      if (shouldZoomOut) {
-        // Step 1: Zoom out, then combined pan + zoom in (like ol-geocoder)
-        view.animate({ zoom: flyZoom, duration: zoomOutDuration }, () => {
+  const selectResult = useCallback(
+    (result: GeocoderResult) => {
+      const view = map.getView();
+      const currentZoom = view.getZoom() ?? 10;
+      const shouldZoomOut = currentZoom > flyOutThreshold;
+      const flyZoom = shouldZoomOut ? Math.max(currentZoom - 4, flyOutZoomMin) : currentZoom;
+      const padding = [fitPadding, fitPadding, fitPadding, fitPadding] as [
+        number,
+        number,
+        number,
+        number,
+      ];
+      // Use result-specific zoom if provided, otherwise fall back to targetZoom prop
+      const finalZoom = result.zoom ?? targetZoom;
+
+      if (result.extent) {
+        if (shouldZoomOut) {
+          // Step 1: Zoom out, then fit to extent (combined pan + zoom)
+          view.animate({ zoom: flyZoom, duration: zoomOutDuration }, () => {
+            view.fit(result.extent!, { padding, duration: flyToDuration });
+          });
+        } else {
+          view.fit(result.extent, { padding, duration: flyToDuration });
+        }
+      } else if (result.center) {
+        if (shouldZoomOut) {
+          // Step 1: Zoom out, then combined pan + zoom in (like ol-geocoder)
+          view.animate({ zoom: flyZoom, duration: zoomOutDuration }, () => {
+            view.animate({ center: result.center, zoom: finalZoom, duration: flyToDuration });
+          });
+        } else {
+          // Combined pan + zoom in one smooth animation
           view.animate({ center: result.center, zoom: finalZoom, duration: flyToDuration });
-        });
-      } else {
-        // Combined pan + zoom in one smooth animation
-        view.animate({ center: result.center, zoom: finalZoom, duration: flyToDuration });
+        }
       }
-    }
 
-    setSelectedId(result.id);
-    setOpen(false);
-    setStatus(`Selected ${result.label}`);
+      // Debug callback for selection
+      onDebug?.({
+        type: 'select',
+        data: { result, zoom: finalZoom, currentZoom, shouldZoomOut },
+      });
+    },
+    [
+      map,
+      flyOutThreshold,
+      flyOutZoomMin,
+      fitPadding,
+      targetZoom,
+      zoomOutDuration,
+      flyToDuration,
+      onDebug,
+    ],
+  );
 
-    // Debug callback for selection
-    onDebug?.({
-      type: 'select',
-      data: { result, zoom: finalZoom, currentZoom, shouldZoomOut },
-    });
-  };
+  const loadOptions = useCallback(
+    (
+      inputValue: string,
+      callback: (options: OptionsOrGroups<GeocoderResult, GeocoderGroup>) => void,
+    ) => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
 
-  const clearSearch = () => {
-    setQuery('');
-    setResults([]);
-    setOpen(false);
-    setActiveIndex(-1);
-    setSelectedId(null);
-    setStatus('');
-    inputRef.current?.focus();
+      if (inputValue.length < minChars) {
+        setIsSearching(false);
+        callback([]);
 
-    // Debug callback for clear
-    onDebug?.({ type: 'clear' });
-  };
+        return;
+      }
 
-  const handleFocus = () => {
-    // Show previous results when focusing the input
-    if (results.length > 0) {
-      setOpen(true);
-      setActiveIndex(-1);
-    }
-  };
+      setIsSearching(true);
 
-  const grouped = groupResults(results);
-  let flatIndex = -1;
+      debounceRef.current = setTimeout(async () => {
+        try {
+          const results = await search(inputValue);
+          const grouped = groupResults(results);
+          const options = Object.entries(grouped).map(([label, groupOptions]) => ({
+            label,
+            options: groupOptions,
+          }));
+
+          callback(options);
+
+          // Debug callback for results
+          onDebug?.({
+            type: 'results',
+            data: { query: inputValue, results, count: results.length },
+          });
+        } catch (error) {
+          console.error('Search error:', error);
+          callback([]);
+        } finally {
+          setIsSearching(false);
+        }
+      }, typeaheadDelay);
+    },
+    [minChars, search, typeaheadDelay, onDebug],
+  );
 
   return (
-    <div className="relative w-full max-w-sm">
-      <div role="status" aria-live="polite" className="sr-only">
-        {status}
-      </div>
-
-      <label htmlFor={id} className="sr-only">
+    <InputGroup className="min-w-xs max-w-sm">
+      <label htmlFor={inputId} className="sr-only">
         Search for a place
       </label>
 
-      <div
-        className="relative bg-white rounded shadow-lg border-2 border-[#0b0c0c] transition-all
-          duration-200 focus-within:ring-2 focus-within:ring-focus"
-      >
-        <IoSearch
-          size={20}
-          className="absolute left-3 top-1/2 -translate-y-1/2 pointer-events-none text-gray-400"
-        />
-
-        <input
-          ref={inputRef}
-          id={id}
-          type="text"
-          role="combobox"
-          aria-autocomplete="list"
-          aria-expanded={open}
-          aria-controls={listboxId}
-          aria-activedescendant={
-            activeIndex >= 0 ? `${listboxId}-option-${activeIndex}` : undefined
-          }
-          value={query}
-          placeholder={placeholder}
-          onChange={(e) => setQuery(e.target.value)}
-          onFocus={handleFocus}
-          onKeyDown={(e) => {
-            if (e.key === 'ArrowDown') {
-              e.preventDefault();
-
-              if (!open && results.length > 0) {
-                setOpen(true);
-              } else {
-                setActiveIndex((i) => Math.min(i + 1, results.length - 1));
-              }
-            }
-
-            if (e.key === 'ArrowUp') {
-              e.preventDefault();
-              setActiveIndex((i) => Math.max(i - 1, 0));
-            }
-
-            if (e.key === 'Enter') {
-              e.preventDefault();
-              const activeResult = results[activeIndex];
-
-              if (activeResult && open) {
-                selectResult(activeResult);
-              } else {
-                performSearch(query);
-              }
-            }
-
-            if (e.key === 'Escape') {
-              e.preventDefault();
-              clearSearch();
-            }
-          }}
-          className="w-full h-12 pl-11 pr-11 border-0 bg-transparent text-base text-gray-800
-            placeholder:text-gray-500 focus:outline-none focus:ring-0"
-        />
-
-        <div className="absolute right-2 top-1/2 -translate-y-1/2">
-          {(() => {
-            if (isSearching) {
-              return (
-                <div className="p-1">
-                  <ImSpinner2 size={22} className="animate-spin text-gray-500" />
-                </div>
-              );
-            }
-
-            if (query) {
-              return (
-                <button
-                  type="button"
-                  onClick={clearSearch}
-                  aria-label="Clear search"
-                  className="p-1 hover:bg-gray-100 rounded transition-colors"
-                >
-                  <IoClose size={20} className="text-gray-500" />
-                </button>
-              );
-            }
-
-            return <></>;
-          })()}
-        </div>
-      </div>
-
-      {/* Results dropdown with Mapbox styling */}
-      {open ? (
-        <div className="absolute z-1000 mt-1.5 w-full bg-white rounded shadow-lg overflow-hidden">
-          {results.length > 0 ? (
-            <div id={listboxId} role="listbox" tabIndex={-1} className="max-h-60 overflow-auto">
-              {Object.entries(grouped).map(([group, items]) => (
-                <div key={group} role="presentation">
-                  <div
-                    className="px-3 py-1.5 text-xs font-semibold text-gray-600 bg-gray-50 sticky
-                      top-0"
-                  >
-                    {group}
-                  </div>
-
-                  <div role="group">
-                    {items.map((item) => {
-                      flatIndex += 1;
-                      const itemIndex = flatIndex;
-                      const isActive = itemIndex === activeIndex;
-                      const isSelected = item.id === selectedId;
-
-                      return (
-                        <div
-                          id={`${listboxId}-option-${itemIndex}`}
-                          key={item.id}
-                          role="option"
-                          aria-selected={isSelected}
-                          tabIndex={-1}
-                          className={`scroll-mt-8 cursor-pointer px-3 py-2 text-sm text-gray-800
-                            transition-colors ${isSelected ? 'bg-blue-50 font-semibold' : ''}
-                            ${isActive && !isSelected ? 'bg-gray-100' : ''}
-                            ${!isSelected && !isActive ? 'hover:bg-gray-50' : ''}`}
-                          onMouseEnter={() => setActiveIndex(itemIndex)}
-                          onMouseDown={() => selectResult(item)}
-                        >
-                          <div className="truncate">{item.label}</div>
-                        </div>
-                      );
-                    })}
-                  </div>
-                </div>
-              ))}
-            </div>
+      <InputPrefix>
+        <InputSwatch>
+          {isSearching ? (
+            <LuLoaderCircle aria-hidden className="animate-spin" />
           ) : (
-            (() => {
-              if (query && !isSearching) {
-                return (
-                  <div className="px-3 py-6 text-center text-sm text-gray-500">
-                    {status || 'No results found'}
-                  </div>
-                );
-              }
-
-              return <></>;
-            })()
+            <LuSearch aria-hidden />
           )}
-        </div>
-      ) : null}
-    </div>
+        </InputSwatch>
+      </InputPrefix>
+
+      <AsyncSelect<GeocoderResult, false, GeocoderGroup>
+        inputId={inputId}
+        value={value}
+        placeholder={placeholder}
+        loadOptions={loadOptions}
+        getOptionLabel={(option) => option.label}
+        getOptionValue={(option) => option.id}
+        isClearable
+        hideLoadingIndicator
+        noOptionsMessage={({ inputValue }) =>
+          inputValue.length < minChars
+            ? `Enter at least ${minChars} characters`
+            : 'No results found'
+        }
+        screenReaderStatus={({ count }) => `${count} result${count === 1 ? '' : 's'} available`}
+        onChange={(option, meta) => {
+          setValue(option);
+
+          if (meta.action === 'select-option' && option) {
+            selectResult(option);
+          } else if (meta.action === 'clear') {
+            // Debug callback for clear
+            onDebug?.({ type: 'clear' });
+          }
+        }}
+      />
+    </InputGroup>
   );
 };

package/src/map/index.ts

@@ -2,7 +2,7 @@ export * from './basemaps';
 export * from './geocoder/index';
 export * from './geometries';
 export * from './LayerSwitcherPanel';
-export * from './LegendPanel';
+export * from './LegendShim';
 export * from './MapControlsOverlay';
 export * from './utils';
 export * from './MapComponent';

package/src/types/utils.ts

@@ -1,13 +1,3 @@
-import type { ComponentProps } from 'react';
-
 // Utility types for better developer experience
 export type PropsWithRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
 export type PropsWithOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-
-export type ExtendProps<
-  // `ComponentProps` internally constrains `Comp` to be `JSXElementConstructor<any>`,
-  // and since our type must have the same constraints to avoid errors, `any` is required here
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  Comp extends keyof React.JSX.IntrinsicElements | React.JSXElementConstructor<any>,
-  Props = object,
-> = Props & Omit<ComponentProps<Comp>, keyof Props>;

package/src/utils/components.ts

@@ -0,0 +1,96 @@
+import { cva } from 'class-variance-authority';
+import { extendTailwindMerge } from 'tailwind-merge';
+
+// This project's border-width scale (border-width-form/standard/wide, see
+// @tpzdsp/eslint-config-dsp/tailwindcss/layout.css) and semantic colour scale
+// (see .../tailwindcss/colors/defra-light.css) are custom theme tokens
+// tailwind-merge has no way to know about by default. Without registering
+// them, tailwind-merge fails to recognise e.g. `border-l-standard` as a
+// border-width utility, misclassifies it as an unrecognised border-colour
+// utility instead, and silently drops it when merged alongside a real colour
+// utility like `border-error` (confirmed via the installed tailwind-merge:
+// `twMerge('border-l-standard border-error')` -> `'border-error'`, the width
+// class vanishes so the border renders at its default 0 width).
+const BORDER_WIDTHS = ['form', 'standard', 'wide'];
+
+const SEMANTIC_COLORS = [
+  'panel',
+  'panel-border',
+  'body',
+  'body-secondary',
+  'accent',
+  'accent-safe',
+  'accent-hover',
+  'accent-shadow',
+  'accent-subtle',
+  'on-accent',
+  'on-accent-subtle',
+  'link',
+  'link-hover',
+  'link-visited',
+  'link-active',
+  'divider',
+  'divider-input',
+  'focus',
+  'on-focus',
+  'error',
+  'error-hover',
+  'error-shadow',
+  'error-subtle',
+  'on-error',
+  'on-error-subtle',
+  'success',
+  'success-subtle',
+  'on-success-subtle',
+  'wash',
+  'neutral-mid',
+  'muted',
+  'neutral-subtle',
+  'on-neutral-subtle',
+  'surface',
+  'on-surface',
+  'surface-divider',
+  'surface-hover',
+  'warning',
+  'warning-subtle',
+  'on-warning',
+  'on-warning-subtle',
+  'disabled',
+  'on-disabled',
+  'info-subtle',
+  'on-info-subtle',
+];
+
+const twMerge = extendTailwindMerge({
+  extend: {
+    theme: {
+      color: SEMANTIC_COLORS,
+    },
+    classGroups: {
+      'border-w': [{ border: BORDER_WIDTHS }],
+      'border-w-x': [{ 'border-x': BORDER_WIDTHS }],
+      'border-w-y': [{ 'border-y': BORDER_WIDTHS }],
+      'border-w-t': [{ 'border-t': BORDER_WIDTHS }],
+      'border-w-r': [{ 'border-r': BORDER_WIDTHS }],
+      'border-w-b': [{ 'border-b': BORDER_WIDTHS }],
+      'border-w-l': [{ 'border-l': BORDER_WIDTHS }],
+    },
+  },
+});
+
+/**
+ * Utility function to merge Tailwind CSS classes with conflict resolution
+ * Uses tailwind-merge to handle conflicting utility classes
+ */
+export const cn = (...classes: (string | undefined | null | false)[]): string => {
+  return twMerge(classes.filter(Boolean).join(' '));
+};
+
+/**
+ * Mixture of `cva` (class-variance-authority) and `twMerge`.
+ */
+export const cvm = <T>(...args: Parameters<typeof cva<T>>): ReturnType<typeof cva<T>> => {
+  const variants = cva<T>(...args);
+
+  return (...props) => cn(variants(...props));
+};

package/src/utils/index.ts

@@ -2,3 +2,4 @@ export * from './utils';
 export * from './auth';
 export * from './constants';
 export * from './date';
+export * from './components';