@deck.gl/widgets 9.1.12 → 9.2.0-alpha.2

package/src/lib/components/icon-menu.tsx

@@ -0,0 +1,89 @@
+import type {JSX} from 'preact';
+import {useState, useRef, useEffect} from 'preact/hooks';
+import {IconButton} from './icon-button';
+
+const MENU_STYLE: JSX.CSSProperties = {
+  position: 'absolute',
+  top: '100%',
+  left: 0,
+  background: 'white',
+  border: '1px solid #ccc',
+  borderRadius: '4px',
+  marginTop: '4px',
+  zIndex: 100
+};
+
+const MENU_ITEM_STYLE: JSX.CSSProperties = {
+  background: 'white',
+  border: 'none',
+  padding: '4px',
+  cursor: 'pointer',
+  pointerEvents: 'auto'
+};
+
+export type IconMenuProps<KeyType = string> = {
+  className: string;
+  icon?: () => JSX.Element;
+  label?: string;
+  menuItems: {value: KeyType; icon: () => JSX.Element; label: string}[];
+  initialItem: KeyType;
+  onItemSelected: (item: KeyType) => void;
+};
+
+/** A component that renders an icon popup menu */
+export function IconMenu<KeyType extends string>(props: IconMenuProps<KeyType>) {
+  const [menuOpen, setMenuOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Close the menu when clicking outside.
+  const handleClickOutside = (event: MouseEvent) => {
+    if (containerRef.current && !containerRef.current.contains(event.target as Node)) {
+      setMenuOpen(false);
+    }
+  };
+
+  useEffect(() => {
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside);
+    };
+  }, [containerRef]);
+
+  const [selectedItem, setSelectedItem] = useState<KeyType>(props.initialItem);
+
+  const handleSelectItem = (item: KeyType) => {
+    setSelectedItem(item);
+    setMenuOpen(false);
+    props.onItemSelected(item);
+  };
+
+  const handleButtonClick = () => setMenuOpen(!menuOpen);
+
+  const selectedMenuItem = props.menuItems.find(item => item.value === selectedItem);
+  const label = props.label || selectedMenuItem?.label || '';
+  const Icon = (props.icon || selectedMenuItem?.icon)!;
+
+  return (
+    <div style={{position: 'relative', display: 'inline-block'}} ref={containerRef}>
+      <IconButton className={props.className} label={label} onClick={handleButtonClick}>
+        <Icon />
+      </IconButton>
+      {menuOpen && (
+        <div style={MENU_STYLE}>
+          <div style={{display: 'flex', flexDirection: 'column'}}>
+            {props.menuItems.map(item => (
+              <button
+                key={item.value}
+                style={MENU_ITEM_STYLE}
+                title={item.label}
+                onClick={() => handleSelectItem(item.value)}
+              >
+                {item.icon}
+              </button>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/lib/components/simple-menu.tsx

@@ -0,0 +1,52 @@
+import type {JSX} from 'preact';
+
+const MENU_STYLE: JSX.CSSProperties = {
+  position: 'absolute',
+  top: '100%',
+  left: 0,
+  background: 'white',
+  border: '1px solid #ccc',
+  borderRadius: '4px',
+  marginTop: '4px',
+  zIndex: 100
+};
+
+const MENU_ITEM_STYLE: JSX.CSSProperties = {
+  background: 'white',
+  border: 'none',
+  padding: '4px',
+  cursor: 'pointer',
+  pointerEvents: 'auto'
+};
+
+export type SimpleMenuProps = {
+  menuItems: {key: string; label: string}[];
+  onItemSelected: (key: string) => void;
+  position: {x: number; y: number};
+  style?: JSX.CSSProperties;
+};
+
+/** Renders a simple dropdown menu at an arbitrary position */
+export const SimpleMenu = (props: SimpleMenuProps) => {
+  const {menuItems, onItemSelected, position, style} = props;
+  const styleOverride: JSX.CSSProperties = {
+    ...MENU_STYLE,
+    ...style,
+    left: `${position.x}px`,
+    top: `${position.y}px`
+  };
+
+  return (
+    <div style={styleOverride}>
+      {menuItems.map(({key, label}) => (
+        <button
+          key={key}
+          style={{...MENU_ITEM_STYLE, display: 'block'}}
+          onClick={_ => onItemSelected(key)}
+        >
+          {label}
+        </button>
+      ))}
+    </div>
+  );
+};

package/src/lib/geocode/geocoder-history.ts

@@ -0,0 +1,73 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {type Geocoder} from './geocoder';
+
+const CURRENT_LOCATION = 'current';
+const LOCAL_STORAGE_KEY = 'deck-geocoder-history';
+
+export type GeocoderHistoryProps = {
+  maxEntries?: number;
+};
+
+/**
+ * An internal, experimental helper class for storing a list of locations in local storage.
+ * @todo Remove the UI related state.
+ */
+export class GeocoderHistory {
+  props: Required<GeocoderHistoryProps>;
+  addressText = '';
+  errorText = '';
+  addressHistory: string[] = [];
+
+  constructor(props: GeocoderHistoryProps) {
+    this.props = {maxEntries: 5, ...props};
+    this.addressHistory = this.loadPreviousAddresses();
+  }
+
+  /** PErform geocoding */
+  async geocode(geocoder: Geocoder, address: string, apiKey: string) {
+    this.errorText = '';
+    this.addressText = address;
+    try {
+      const coordinates = await geocoder.geocode(address, apiKey);
+      if (coordinates) {
+        this.storeAddress(this.addressText);
+        return coordinates;
+      }
+      this.errorText = 'Invalid address';
+    } catch (error) {
+      this.errorText = `${(error as Error).message}`;
+    }
+    return null;
+  }
+
+  loadPreviousAddresses(): string[] {
+    try {
+      const stored = window.localStorage.getItem(LOCAL_STORAGE_KEY);
+      const list = stored && JSON.parse(stored);
+      const addresses = Array.isArray(list)
+        ? list.filter((v): v is string => typeof v === 'string')
+        : [];
+      return addresses;
+    } catch {
+      // ignore
+    }
+    return [];
+  }
+
+  storeAddress(address: string) {
+    const cleaned = address.trim();
+    if (!cleaned || cleaned === CURRENT_LOCATION) {
+      return;
+    }
+    const deduped = [cleaned, ...this.addressHistory.filter(a => a !== cleaned)];
+    this.addressHistory = deduped.slice(0, this.props.maxEntries);
+    try {
+      window.localStorage.setItem(LOCAL_STORAGE_KEY, JSON.stringify(this.addressHistory));
+    } catch {
+      // ignore
+    }
+  }
+}

package/src/lib/geocode/geocoder.ts

@@ -0,0 +1,15 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** A geocoder that translates an address string into a location */
+export type Geocoder = {
+  /** The name of the geocoder, e.g. google, mapbox, ... */
+  name: string;
+  /** Does the geocoder require an api key? */
+  requiresApiKey?: boolean;
+  /** A string that can be used to indicate the accepted format */
+  placeholderLocation?: string;
+  /** Calls the geocoder service, translating an address string into a location */
+  geocode(address: string, apiKey: string): Promise<{longitude: number; latitude: number} | null>;
+};

package/src/lib/geocode/geocoders.ts

@@ -0,0 +1,199 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {type Geocoder} from './geocoder';
+
+const GOOGLE_URL = 'https://maps.googleapis.com/maps/api/geocode/json';
+const MAPBOX_URL = 'https://api.mapbox.com/geocoding/v5/mapbox.places';
+const OPENCAGE_API_URL = 'https://api.opencagedata.com/geocode/v1/json';
+
+/**
+ * A geocoder that uses the google geocoding service
+ * @note Requires an API key from Google
+ * @see https://developers.google.com/maps/documentation/geocoding/get-api-key
+ */
+export const GoogleGeocoder = {
+  name: 'google',
+  requiresApiKey: true,
+  async geocode(
+    address: string,
+    apiKey: string
+  ): Promise<{longitude: number; latitude: number} | null> {
+    const encodedAddress = encodeURIComponent(address);
+    const json = await fetchJson(`${GOOGLE_URL}?address=${encodedAddress}&key=${apiKey}`);
+
+    switch (json.status) {
+      case 'OK':
+        const loc = json.results.length > 0 && json.results[0].geometry.location;
+        return loc ? {longitude: loc.lng, latitude: loc.lat} : null;
+      default:
+        throw new Error(`Google Geocoder failed: ${json.status}`);
+    }
+  }
+} as const satisfies Geocoder;
+
+/**
+ * A geocoder that uses the google geocoding service
+ * @note Requires an API key from Mapbox
+ * @see https://docs.mapbox.com/api/search/geocoding/
+ */
+export const MapboxGeocoder = {
+  name: 'google',
+  requiresApiKey: true,
+  async geocode(
+    address: string,
+    apiKey: string
+  ): Promise<{longitude: number; latitude: number} | null> {
+    const encodedAddress = encodeURIComponent(address);
+    const json = await fetchJson(`${MAPBOX_URL}/${encodedAddress}.json?access_token=${apiKey}`);
+
+    if (Array.isArray(json.features) && json.features.length > 0) {
+      const center = json.features[0].center;
+      if (Array.isArray(center) && center.length >= 2) {
+        return {longitude: center[0], latitude: center[1]};
+      }
+    }
+    return null;
+  }
+} as const satisfies Geocoder;
+
+/**
+ * A geocoder that uses the google geocoding service
+ * @note Requires an API key from OpenCageData
+ * @see https://opencagedata.com/api
+ */
+export const OpenCageGeocoder = {
+  name: 'opencage',
+  requiresApiKey: true,
+  async geocode(
+    address: string,
+    key: string
+  ): Promise<{longitude: number; latitude: number} | null> {
+    const encodedAddress = encodeURIComponent(address);
+    const data = await fetchJson(`${OPENCAGE_API_URL}?q=${encodedAddress}&key=${key}`);
+    if (Array.isArray(data.results) && data.results.length > 0) {
+      const geometry = data.results[0].geometry;
+      return {longitude: geometry.lng, latitude: geometry.lat};
+    }
+    return null;
+  }
+} as const satisfies Geocoder;
+
+/**
+ * A geocoder adapter that wraps the browser's geolocation API. Always returns the user's current location.
+ * @note Not technically a geocoder, but a geolocation service that provides a source of locations.
+ * @note The user must allow location access for this to work.
+ */
+export const CurrentLocationGeocoder = {
+  name: 'current',
+  requiresApiKey: false,
+  /** Attempt to call browsers geolocation API */
+  async geocode(): Promise<{longitude: number; latitude: number} | null> {
+    if (!navigator.geolocation) {
+      throw new Error('Geolocation not supported');
+    }
+    return new Promise((resolve, reject) => {
+      navigator.geolocation.getCurrentPosition(
+        /** @see https://developer.mozilla.org/docs/Web/API/GeolocationPosition */
+        (position: GeolocationPosition) => {
+          const {longitude, latitude} = position.coords;
+          resolve({longitude, latitude});
+        },
+        /** @see https://developer.mozilla.org/docs/Web/API/GeolocationPositionError */
+        (error: GeolocationPositionError) => reject(new Error(error.message))
+      );
+    });
+  }
+} as const satisfies Geocoder;
+
+/** Fetch JSON, catching HTTP errors */
+async function fetchJson(url: string): Promise<any> {
+  let response: Response;
+  try {
+    response = await fetch(url);
+  } catch (error) {
+    // Annoyingly, fetch reports some errors (e.g. CORS) using excpetions, not response.ok
+    throw new Error(`CORS error? ${error}. ${url}: `);
+  }
+  if (!response.ok) {
+    throw new Error(`${response.statusText}. ${url}: `);
+  }
+  const data = await response.json();
+  if (!data) {
+    throw new Error(`No data returned. ${url}`);
+  }
+  return data;
+}
+
+/**
+ * Parse a coordinate string.
+ * Supports comma- or semicolon-separated values.
+ * Heuristically determines which value is longitude and which is latitude.
+ */
+export const CoordinatesGeocoder = {
+  name: 'coordinates',
+  requiresApiKey: false,
+  placeholderLocation: `-122.45, 37.8 or 37°48'N, 122°27'W`,
+  async geocode(address: string): Promise<{longitude: number; latitude: number} | null> {
+    return parseCoordinates(address) || null;
+  }
+} as const satisfies Geocoder;
+
+/**
+ * Parse an input string for coordinates.
+ * Supports comma- or semicolon-separated values.
+ * Heuristically determines which value is longitude and which is latitude.
+ */
+function parseCoordinates(input) {
+  input = input.trim();
+  const parts = input.split(/[,;]/).map(p => p.trim());
+  if (parts.length < 2) return null;
+  const first = parseCoordinatePart(parts[0]);
+  const second = parseCoordinatePart(parts[1]);
+  if (first === null || second === null) return null;
+  // Use a heuristic:
+  // If one number exceeds 90 in absolute value, it's likely a longitude.
+  if (Math.abs(first) > 90 && Math.abs(second) <= 90) {
+    return {longitude: first, latitude: second};
+  } else if (Math.abs(second) > 90 && Math.abs(first) <= 90) {
+    return {longitude: second, latitude: first};
+  }
+  // If both are <= 90, assume order: latitude, longitude.
+  return {latitude: first, longitude: second};
+}
+
+/**
+ * Parse a single coordinate part (which may be in decimal or DMS format).
+ */
+function parseCoordinatePart(s: string): number | null {
+  s = s.trim();
+  // If the string contains a degree symbol or similar markers, use DMS parsing.
+  if (s.includes('°') || s.includes("'") || s.includes('"')) {
+    const value = dmsToDecimal(s);
+    return isNaN(value) ? null : value;
+  }
+  // Otherwise, check for a cardinal letter and remove it.
+  let sign = 1;
+  if (/[SW]/i.test(s)) sign = -1;
+  s = s.replace(/[NSEW]/gi, '');
+  const value = parseFloat(s);
+  return isNaN(value) ? null : sign * value;
+}
+
+/** Convert a DMS string (e.g. "37°48'00\"N") to decimal degrees. */
+function dmsToDecimal(s: string): number {
+  // A simple regex to extract degrees, minutes, seconds and direction.
+  const regex = /(\d+)[°d]\s*(\d+)?['′m]?\s*(\d+(?:\.\d+)?)?[\"″s]?\s*([NSEW])?/i;
+  const match = s.match(regex);
+  if (!match) return NaN;
+  const degrees = parseFloat(match[1]) || 0;
+  const minutes = parseFloat(match[2]) || 0;
+  const seconds = parseFloat(match[3]) || 0;
+  const direction = match[4] || '';
+  let dec = degrees + minutes / 60 + seconds / 3600;
+  if (/[SW]/i.test(direction)) {
+    dec = -dec;
+  }
+  return dec;
+}

package/src/loading-widget.tsx

@@ -0,0 +1,67 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {WidgetPlacement, Layer} from '@deck.gl/core';
+import {render} from 'preact';
+import {Widget, WidgetProps} from '@deck.gl/core';
+import {IconButton} from './lib/components/icon-button';
+
+/** Properties for the LoadingWidget */
+export type LoadingWidgetProps = WidgetProps & {
+  /** Widget positioning within the view. Default 'top-left'. */
+  placement?: WidgetPlacement;
+  /** Tooltip message when loading */
+  label?: string;
+};
+
+/**
+ * A non-interactive widget that shows a loading spinner if any layers are loading data
+ */
+export class LoadingWidget extends Widget<LoadingWidgetProps> {
+  static defaultProps: Required<LoadingWidgetProps> = {
+    ...Widget.defaultProps,
+    id: 'loading',
+    placement: 'top-left',
+    label: 'Loading layer data'
+  };
+
+  className = 'deck-widget-loading';
+  placement: WidgetPlacement = 'top-left';
+  loading = true;
+
+  constructor(props: LoadingWidgetProps = {}) {
+    super(props, LoadingWidget.defaultProps);
+    this.placement = props.placement ?? this.placement;
+  }
+
+  setProps(props: Partial<LoadingWidgetProps>) {
+    this.placement = props.placement ?? this.placement;
+    super.setProps(props);
+  }
+
+  onRenderHTML(rootElement: HTMLElement): void {
+    render(
+      // TODO(ibgreen) - this should not be a button, but styling is so nested that it is easier to reuse this component.
+      this.loading && (
+        <IconButton
+          className="deck-widget-spinner-icon"
+          label={this.props.label}
+          onClick={this.handleClick.bind(this)}
+        />
+      ),
+      rootElement
+    );
+  }
+
+  onRedraw({layers}: {layers: Layer[]}): void {
+    const loading = !layers.some(layer => !layer.isLoaded);
+    if (loading !== this.loading) {
+      this.loading = loading;
+      this.updateHTML();
+    }
+  }
+
+  // TODO(ibgreen) - this should not be a button, see above.
+  handleClick() {}
+}

package/src/reset-view-widget.tsx

@@ -2,17 +2,16 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-/* global document */
 import type {WidgetPlacement} from '@deck.gl/core';
 import {render} from 'preact';
-import {WidgetImpl, WidgetImplProps} from './widget-impl';
-import {IconButton} from './components';
+import {Widget, WidgetProps} from '@deck.gl/core';
+import {IconButton} from './lib/components/icon-button';
 
 /** @todo - is the the best we can do? */
 type ViewState = Record<string, unknown>;
 
 /** Properties for the ResetViewWidget */
-export type ResetViewWidgetProps = WidgetImplProps & {
+export type ResetViewWidgetProps = WidgetProps & {
   /** Widget positioning within the view. Default 'top-left'. */
   placement?: WidgetPlacement;
   /** Tooltip message */
@@ -26,9 +25,9 @@ export type ResetViewWidgetProps = WidgetImplProps & {
 /**
  * A button widget that resets the view state of deck to an initial state.
  */
-export class ResetViewWidget extends WidgetImpl<ResetViewWidgetProps> {
+export class ResetViewWidget extends Widget<ResetViewWidgetProps> {
   static defaultProps: Required<ResetViewWidgetProps> = {
-    ...WidgetImpl.defaultProps,
+    ...Widget.defaultProps,
     id: 'reset-view',
     placement: 'top-left',
     label: 'Reset View',
@@ -40,7 +39,7 @@ export class ResetViewWidget extends WidgetImpl<ResetViewWidgetProps> {
   placement: WidgetPlacement = 'top-left';
 
   constructor(props: ResetViewWidgetProps = {}) {
-    super({...ResetViewWidget.defaultProps, ...props});
+    super(props, ResetViewWidget.defaultProps);
     this.placement = props.placement ?? this.placement;
   }
 
@@ -49,16 +48,14 @@ export class ResetViewWidget extends WidgetImpl<ResetViewWidgetProps> {
     super.setProps(props);
   }
 
-  onRenderHTML() {
-    const element = this.element;
-    if (!element) return;
+  onRenderHTML(rootElement: HTMLElement): void {
     render(
       <IconButton
         className="deck-widget-reset-focus"
         label={this.props.label}
         onClick={this.handleClick.bind(this)}
       />,
-      element
+      rootElement
     );
   }