@tpzdsp/next-toolkit 1.12.1 → 1.14.0

package/src/map/createControlButton.ts

@@ -0,0 +1,72 @@
+/**
+ * Utility function to create a standardized OpenLayers control button
+ * with consistent styling and accessibility attributes.
+ *
+ * @example
+ * const button = createControlButton({
+ *   ariaLabel: 'Toggle feature',
+ *   title: 'Feature control',
+ *   iconSvg: '<path d="M..." />',
+ * });
+ */
+
+// Common SVG icons for map controls
+export const CONTROL_ICONS = {
+  PLUS: '<path d="M12 5v14m-7-7h14" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>',
+  MINUS: '<path d="M5 12h14" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>',
+  MAP_LAYERS:
+    '<path d="M20.5 3l-5.7 2.1-6-2L3.5 5c-.3.1-.5.5-.5.8v15.2c0 .3.2.6.5.7l5.7-2.1 6 2 5.3-1.9c.3-.1.5-.4.5-.7V3.8c0-.3-.2-.6-.5-.8zM10 5.2l4 1.3v12.3l-4-1.3V5.2zm-6 1.1l4-1.4v12.3l-4 1.4V6.3zm16 12.4l-4 1.4V7.8l4-1.4v12.3z"/>',
+  EXPAND:
+    '<path d="M8 3H5a2 2 0 0 0-2 2v3m18 0V5a2 2 0 0 0-2-2h-3m0 18h3a2 2 0 0 0 2-2v-3M3 16v3a2 2 0 0 0 2 2h3" stroke="currentColor" stroke-width="2" fill="none" stroke-linecap="round" stroke-linejoin="round"/>',
+  COLLAPSE:
+    '<path d="M8 3v3a2 2 0 0 1-2 2H3m18 0h-3a2 2 0 0 1-2-2V3m0 18v-3a2 2 0 0 1 2-2h3M3 16h3a2 2 0 0 1 2 2v3" stroke="currentColor" stroke-width="2" fill="none" stroke-linecap="round" stroke-linejoin="round"/>',
+};
+
+export type ControlButtonOptions = {
+  /** Accessible label for screen readers */
+  ariaLabel: string;
+  /** Tooltip text shown on hover */
+  title: string;
+  /** SVG path data or element for the button icon */
+  iconSvg: string;
+  /** Additional CSS classes to apply */
+  className?: string;
+  /** Button type, defaults to 'button' */
+  type?: 'button' | 'submit' | 'reset';
+  /** Whether this button controls a popup/dialog */
+  hasPopup?: boolean;
+};
+
+/**
+ * Creates a standardized control button with proper accessibility attributes
+ * and consistent styling via the `ol-btn` base class.
+ */
+export const createControlButton = (options: ControlButtonOptions): HTMLButtonElement => {
+  const { ariaLabel, title, iconSvg, className = '', type = 'button', hasPopup = false } = options;
+
+  const button = document.createElement('button');
+
+  button.setAttribute('aria-label', ariaLabel);
+  button.setAttribute('title', title);
+  button.type = type;
+  button.className = `ol-btn ${className}`.trim();
+
+  if (hasPopup) {
+    button.setAttribute('aria-haspopup', 'dialog');
+    button.setAttribute('aria-expanded', 'false');
+  }
+
+  // Create SVG icon
+  const icon = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+
+  icon.setAttribute('width', '20');
+  icon.setAttribute('height', '20');
+  icon.setAttribute('viewBox', '0 0 24 24');
+  icon.setAttribute('fill', 'currentColor');
+  icon.setAttribute('aria-hidden', 'true');
+  icon.innerHTML = iconSvg;
+
+  button.appendChild(icon);
+
+  return button;
+};

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

@@ -0,0 +1,115 @@
+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) => {
+    // Immediately execute callback if provided (simulating instant animation)
+    if (typeof callback === 'function') {
+      callback(true);
+    }
+  });
+  fit = vi.fn();
+  getZoom = vi.fn(() => 5);
+}
+
+const mockView = new MockView({ center: [0, 0], zoom: 5 });
+const mockMap = new Map({ view: mockView });
+
+describe('Geocoder', () => {
+  it('renders results and allows keyboard selection', async () => {
+    const search = vi.fn().mockResolvedValue([{ id: '1', label: 'London', center: [0, 0] }]);
+
+    render(<Geocoder map={mockMap} search={search} />);
+
+    const input = screen.getByRole('combobox');
+    const user = userEvent.setup();
+
+    // Type into the input
+    await user.type(input, 'Lon');
+
+    // Press Enter to trigger search
+    await user.keyboard('{Enter}');
+
+    // Wait for the result to appear
+    const option = await screen.findByText('London');
+
+    expect(option).toBeInTheDocument();
+
+    // Navigate to the option using arrow keys and select
+    await user.keyboard('{ArrowDown}{Enter}');
+
+    // Verify the map animation was called with center and zoom (default zoom is 14)
+    expect(mockView.animate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        center: [0, 0],
+        zoom: 14,
+        duration: 1500,
+      }),
+    );
+  });
+
+  it('fits to extent when result has extent', async () => {
+    const search = vi
+      .fn()
+      .mockResolvedValue([{ id: '1', label: 'Greater London', extent: [-0.5, 51.3, 0.3, 51.7] }]);
+
+    render(<Geocoder map={mockMap} search={search} />);
+
+    const input = screen.getByRole('combobox');
+    const user = userEvent.setup();
+
+    await user.type(input, 'Greater{Enter}');
+
+    const option = await screen.findByText('Greater London');
+
+    await user.click(option);
+
+    // Should call fit with extent and padding (no zoom-out animation since currentZoom=5 < flyOutThreshold=8)
+    expect(mockView.fit).toHaveBeenCalledWith(
+      [-0.5, 51.3, 0.3, 51.7],
+      expect.objectContaining({
+        padding: [40, 40, 40, 40],
+        duration: 1500,
+      }),
+    );
+  });
+
+  it('does not search when query is too short', async () => {
+    const search = vi.fn().mockResolvedValue([]);
+
+    render(<Geocoder map={mockMap} search={search} minChars={3} />);
+
+    const input = screen.getByRole('combobox');
+    const user = userEvent.setup();
+
+    await user.type(input, 'Lo{Enter}');
+
+    // Search should not be called because query is too short (2 chars < minChars 3)
+    expect(search).not.toHaveBeenCalled();
+  });
+
+  it('closes dropdown on Escape key', async () => {
+    const search = vi.fn().mockResolvedValue([{ id: '1', label: 'London', center: [0, 0] }]);
+
+    render(<Geocoder map={mockMap} search={search} />);
+
+    const input = screen.getByRole('combobox');
+    const user = userEvent.setup();
+
+    await user.type(input, 'London{Enter}');
+
+    const option = await screen.findByText('London');
+
+    expect(option).toBeInTheDocument();
+
+    await user.keyboard('{Escape}');
+
+    // Results should be cleared and dropdown closed
+    expect(screen.queryByText('London')).not.toBeInTheDocument();
+    expect(input).toHaveValue('');
+  });
+});

package/src/map/geocoder/Geocoder.tsx

@@ -0,0 +1,393 @@
+'use client';
+
+import { useId, useRef, useState } from 'react';
+
+import type Map from 'ol/Map';
+
+import { groupResults } from './groupResults';
+import type { GeocoderResult } from './types';
+
+// SVG Icons matching Mapbox GL Geocoder style
+const SearchIcon = () => (
+  <svg
+    className="absolute left-3 top-1/2 -translate-y-1/2 pointer-events-none"
+    width="20"
+    height="20"
+    viewBox="0 0 18 18"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path
+      d="M7.5 13.5C10.8137 13.5 13.5 10.8137 13.5 7.5C13.5 4.18629 10.8137 1.5 7.5 1.5C4.18629 1.5 1.5 4.18629 1.5 7.5C1.5 10.8137 4.18629 13.5 7.5 13.5Z"
+      stroke="#757575"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+
+    <path
+      d="M16.5 16.5L11.625 11.625"
+      stroke="#757575"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+const ClearIcon = () => (
+  <svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M15 5L5 15M5 5L15 15"
+      stroke="#757575"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+const LoadingIcon = () => (
+  <svg
+    className="animate-spin"
+    width="26"
+    height="26"
+    viewBox="0 0 26 26"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <circle
+      cx="13"
+      cy="13"
+      r="10"
+      stroke="#757575"
+      strokeWidth="3"
+      strokeLinecap="round"
+      strokeDasharray="60"
+      strokeDashoffset="40"
+    />
+  </svg>
+);
+
+// Animation defaults - can be overridden via props
+const DEFAULT_TARGET_ZOOM = 14;
+const DEFAULT_FLY_OUT_ZOOM_MIN = 6;
+const DEFAULT_FLY_OUT_THRESHOLD = 8; // Only zoom out if current zoom > this
+const DEFAULT_ZOOM_OUT_DURATION = 800;
+const DEFAULT_FLY_TO_DURATION = 1500;
+const DEFAULT_FIT_PADDING = 40;
+
+export type GeocoderProps = {
+  map: Map;
+  search: (query: string) => Promise<GeocoderResult[]>;
+  placeholder?: string;
+  minChars?: number;
+  id?: string;
+  /** Target zoom level when flying to a location (default: 14) */
+  targetZoom?: number;
+  /** Minimum zoom level when zooming out for fly effect (default: 6) */
+  flyOutZoomMin?: number;
+  /** Only zoom out if current zoom is above this threshold (default: 8) */
+  flyOutThreshold?: number;
+  /** Duration of zoom out animation in ms (default: 800) */
+  zoomOutDuration?: number;
+  /** Duration of fly-to animation in ms (default: 1500) */
+  flyToDuration?: number;
+  /** Padding around extent when fitting (default: 40) */
+  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
+};
+
+export const Geocoder = ({
+  map,
+  search,
+  placeholder = 'Search for a place',
+  minChars = 3,
+  id: providedId,
+  targetZoom = DEFAULT_TARGET_ZOOM,
+  flyOutZoomMin = DEFAULT_FLY_OUT_ZOOM_MIN,
+  flyOutThreshold = DEFAULT_FLY_OUT_THRESHOLD,
+  zoomOutDuration = DEFAULT_ZOOM_OUT_DURATION,
+  flyToDuration = DEFAULT_FLY_TO_DURATION,
+  fitPadding = DEFAULT_FIT_PADDING,
+  onDebug,
+}: 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 [isSearching, setIsSearching] = useState(false);
+
+  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;
+    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,
+        });
+      }
+    }
+
+    setSelectedId(result.id);
+    setOpen(false);
+    setStatus(`Selected ${result.label}`);
+
+    // Debug callback for selection
+    onDebug?.({
+      type: 'select',
+      data: { result, zoom: finalZoom, currentZoom, shouldZoomOut },
+    });
+  };
+
+  const clearSearch = () => {
+    setQuery('');
+    setResults([]);
+    setOpen(false);
+    setActiveIndex(-1);
+    setSelectedId(null);
+    setStatus('');
+    inputRef.current?.focus();
+
+    // Debug callback for clear
+    onDebug?.({ type: 'clear' });
+  };
+
+  const handleFocus = () => {
+    // Show previous results when focusing the input
+    if (results.length > 0) {
+      setOpen(true);
+      setActiveIndex(-1);
+    }
+  };
+
+  const grouped = groupResults(results);
+  let flatIndex = -1;
+
+  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">
+        Search for a place
+      </label>
+
+      {/* Mapbox-style geocoder container */}
+      <div className="relative bg-white rounded shadow-lg transition-all duration-200">
+        <SearchIcon />
+
+        <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();
+              }
+            }
+
+            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"
+        />
+
+        {/* Clear or Loading button */}
+        <div className="absolute right-2 top-1/2 -translate-y-1/2">
+          {(() => {
+            if (isSearching) {
+              return (
+                <div className="p-1">
+                  <LoadingIcon />
+                </div>
+              );
+            }
+
+            if (query) {
+              return (
+                <button
+                  type="button"
+                  onClick={clearSearch}
+                  aria-label="Clear search"
+                  className="p-1 hover:bg-gray-100 rounded transition-colors"
+                >
+                  <ClearIcon />
+                </button>
+              );
+            }
+
+            return null;
+          })()}
+        </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" 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 isActive = flatIndex === activeIndex;
+                      const isSelected = item.id === selectedId;
+
+                      return (
+                        <div
+                          id={`${listboxId}-option-${flatIndex}`}
+                          key={item.id}
+                          role="option"
+                          aria-selected={isSelected}
+                          tabIndex={-1}
+                          className={`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(flatIndex)}
+                          onMouseDown={() => selectResult(item)}
+                        >
+                          <div className="truncate">{item.label}</div>
+                        </div>
+                      );
+                    })}
+                  </div>
+                </div>
+              ))}
+            </div>
+          ) : (
+            (() => {
+              if (query && !isSearching) {
+                return (
+                  <div className="px-3 py-6 text-center text-sm text-gray-500">
+                    {status || 'No results found'}
+                  </div>
+                );
+              }
+
+              return null;
+            })()
+          )}
+        </div>
+      ) : null}
+    </div>
+  );
+};

package/src/map/geocoder/groupResults.ts

@@ -0,0 +1,12 @@
+import type { GeocoderResult, GroupedResults } from './types';
+
+export const groupResults = (results: GeocoderResult[]): GroupedResults => {
+  return results.reduce<GroupedResults>((acc, result) => {
+    const key = result.group ?? 'Results';
+
+    acc[key] ??= [];
+    acc[key].push(result);
+
+    return acc;
+  }, {});
+};

package/src/map/geocoder/index.ts

@@ -0,0 +1,4 @@
+export { Geocoder } from './Geocoder';
+export type { GeocoderProps } from './Geocoder';
+export { groupResults } from './groupResults';
+export type { GeocoderResult, GroupedResults } from './types';

package/src/map/geocoder/types.ts

@@ -0,0 +1,11 @@
+export type GeocoderResult = {
+  id: string;
+  label: string;
+  group?: string;
+  extent?: [number, number, number, number];
+  center?: [number, number];
+  /** Optional zoom level for this result (e.g., city=12, street=16, building=18) */
+  zoom?: number;
+};
+
+export type GroupedResults = Record<string, GeocoderResult[]>;

package/src/map/index.ts

@@ -1,7 +1,10 @@
 export * from './basemaps';
-export * from './geocoder';
+export * from './geocoder/index';
 export * from './geometries';
+export * from './createControlButton';
 export * from './LayerSwitcherControl';
+export * from './LayerSwitcherPanel';
+export * from './FullScreenControl';
 export * from './utils';
 export * from './MapComponent';
 export * from './MapContext';