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

package/src/gimbal-widget.tsx

@@ -0,0 +1,188 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Widget, LinearInterpolator} from '@deck.gl/core';
+import type {Viewport, WidgetPlacement, WidgetProps} from '@deck.gl/core';
+import {render} from 'preact';
+
+export type GimbalWidgetProps = WidgetProps & {
+  placement?: WidgetPlacement;
+  /** View to attach to and interact with. Required when using multiple views. */
+  viewId?: string | null;
+  /** Tooltip message. */
+  label?: string;
+  /** Width of gimbal lines */
+  strokeWidth?: number;
+  /** Transition duration in ms when resetting rotation. */
+  transitionDuration?: number;
+};
+
+export class GimbalWidget extends Widget<GimbalWidgetProps> {
+  static defaultProps: Required<GimbalWidgetProps> = {
+    ...Widget.defaultProps,
+    id: 'gimbal',
+    placement: 'top-left',
+    viewId: undefined!,
+    label: 'Gimbal',
+    strokeWidth: 1.5,
+    transitionDuration: 200
+  };
+
+  className = 'deck-widget-gimbal';
+  placement: WidgetPlacement = 'top-left';
+  viewId?: string | null = null;
+
+  constructor(props: GimbalWidgetProps = {}) {
+    super(props, GimbalWidget.defaultProps);
+    this.setProps(this.props);
+  }
+
+  setProps(props: Partial<GimbalWidgetProps>) {
+    this.placement = props.placement ?? this.placement;
+    this.viewId = props.viewId ?? this.viewId;
+    super.setProps(props);
+  }
+
+  onRenderHTML(rootElement: HTMLElement): void {
+    const {rotationOrbit, rotationX} = this.getNormalizedRotation();
+    // Note - we use CSS 3D transforms instead of SVG 2D transforms
+    const ui = (
+      <div className="deck-widget-button" style={{perspective: 100, pointerEvents: 'auto'}}>
+        <button
+          type="button"
+          onClick={() => {
+            this.resetOrbitView();
+          }}
+          title={this.props.label}
+          style={{position: 'relative', width: 26, height: 26}}
+        >
+          {/* Outer ring */}
+          <svg
+            className="gimbal-outer-ring"
+            width="100%"
+            height="100%"
+            viewBox="0 0 26 26"
+            style={{
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              transform: `rotateY(${rotationOrbit}deg)`
+            }}
+          >
+            <circle
+              cx="13"
+              cy="13"
+              r="10"
+              stroke="var(--icon-gimbal-outer-color, rgb(68, 92, 204))"
+              strokeWidth={this.props.strokeWidth}
+              fill="none"
+            />
+          </svg>
+
+          {/* Inner ring */}
+          <svg
+            className="gimbal-inner-ring"
+            width="100%"
+            height="100%"
+            viewBox="0 0 26 26"
+            style={{
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              transform: `rotateX(${rotationX}deg)`
+            }}
+          >
+            <circle
+              cx="13"
+              cy="13"
+              r="7"
+              stroke="var(--icon-gimbal-inner-color, rgb(240, 92, 68))"
+              strokeWidth={this.props.strokeWidth}
+              fill="none"
+            />
+          </svg>
+        </button>
+      </div>
+    );
+
+    render(ui, rootElement);
+  }
+
+  onViewportChange(viewport: Viewport) {
+    this.updateHTML();
+  }
+
+  resetOrbitView() {
+    const viewId = this.getViewId();
+    const viewState = this.getViewState(viewId);
+    if ('rotationOrbit' in viewState || 'rotationX' in viewState) {
+      const nextViewState = {
+        ...viewState,
+        rotationOrbit: 0,
+        rotationX: 0,
+        transitionDuration: this.props.transitionDuration,
+        transitionInterpolator: new LinearInterpolator({
+          transitionProps: ['rotationOrbit', 'rotationX']
+        })
+      };
+      // @ts-ignore Using private method temporary until there's a public one
+      this.deck._onViewStateChange({viewId, viewState: nextViewState, interactionState: {}});
+    }
+  }
+
+  getNormalizedRotation() {
+    const viewState = this.getViewState(this.getViewId());
+    const [rz, rx] = this.getRotation(viewState);
+    const rotationOrbit = normalizeAndClampAngle(rz);
+    const rotationX = normalizeAndClampAngle(rx);
+    return {rotationOrbit, rotationX};
+  }
+
+  getRotation(viewState?: any): [number, number] {
+    if (viewState && ('rotationOrbit' in viewState || 'rotationX' in viewState)) {
+      return [-(viewState.rotationOrbit || 0), viewState.rotationX || 0];
+    }
+    return [0, 0];
+  }
+
+  // Move to Widget/WidgetManager?
+
+  getViewId() {
+    const viewId = this.viewId || 'OrbitView';
+    return viewId;
+  }
+
+  getViewState(viewId: string) {
+    const viewManager = this.getViewManager();
+    const viewState = (viewId && viewManager.getViewState(viewId)) || viewManager.viewState;
+    return viewState;
+  }
+
+  getViewManager() {
+    // @ts-expect-error protected
+    const viewManager = this.deck?.viewManager;
+    if (!viewManager) {
+      throw new Error('wigdet must be added to a deck instance');
+    }
+    return viewManager;
+  }
+}
+
+function normalizeAndClampAngle(angle: number): number {
+  // Bring angle into [-180, 180]
+  let normalized = ((((angle + 180) % 360) + 360) % 360) - 180;
+
+  // Avoid rotating the gimbal rings to close to 90 degrees as they will visually disappear
+  const AVOID_ANGLE_DELTA = 10;
+  const distanceFrom90 = normalized - 90;
+  if (Math.abs(distanceFrom90) < AVOID_ANGLE_DELTA) {
+    if (distanceFrom90 < AVOID_ANGLE_DELTA) {
+      normalized = 90 + AVOID_ANGLE_DELTA;
+    } else if (distanceFrom90 > -AVOID_ANGLE_DELTA) {
+      normalized = 90 - AVOID_ANGLE_DELTA;
+    }
+  }
+  // Clamp to [-80, 80]
+  return normalized; // Math.max(-80, Math.min(80, normalized));
+}

package/src/index.ts

@@ -2,21 +2,71 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-export {FullscreenWidget} from './fullscreen-widget';
-export {CompassWidget} from './compass-widget';
+// Navigation widgets
 export {ZoomWidget} from './zoom-widget';
-export {ScreenshotWidget} from './screenshot-widget';
 export {ResetViewWidget} from './reset-view-widget';
 
+// Geospatial widgets
+export {CompassWidget} from './compass-widget';
+export {GimbalWidget} from './gimbal-widget';
+export {ScaleWidget as _ScaleWidget} from './scale-widget';
+export {GeocoderWidget as _GeocoderWidget} from './geocoder-widget';
+
+// Utility widgets
+export {FullscreenWidget} from './fullscreen-widget';
+export {ScreenshotWidget} from './screenshot-widget';
+export {LoadingWidget as _LoadingWidget} from './loading-widget';
+export {FpsWidget as _FpsWidget} from './fps-widget';
+export {ThemeWidget as _ThemeWidget} from './theme-widget';
+export {InfoWidget as _InfoWidget} from './info-widget';
+export {StatsWidget as _StatsWidget} from './stats-widget';
+export {ContextMenuWidget as _ContextMenuWidget} from './context-menu-widget';
+export {SplitterWidget as _SplitterWidget} from './splitter-widget';
+export {TimelineWidget as _TimelineWidget} from './timeline-widget';
+export {ViewSelectorWidget as _ViewSelectorWidget} from './view-selector-widget';
+
 export type {FullscreenWidgetProps} from './fullscreen-widget';
 export type {CompassWidgetProps} from './compass-widget';
 export type {ZoomWidgetProps} from './zoom-widget';
 export type {ScreenshotWidgetProps} from './screenshot-widget';
 export type {ResetViewWidgetProps} from './reset-view-widget';
+export type {GeocoderWidgetProps} from './geocoder-widget';
+export type {LoadingWidgetProps} from './loading-widget';
+export type {FpsWidgetProps} from './fps-widget';
+export type {ScaleWidgetProps} from './scale-widget';
+export type {ThemeWidgetProps} from './theme-widget';
+export type {InfoWidgetProps} from './info-widget';
+export type {StatsWidgetProps} from './stats-widget';
+export type {ContextMenuWidgetProps} from './context-menu-widget';
+export type {SplitterWidgetProps} from './splitter-widget';
+export type {TimelineWidgetProps} from './timeline-widget';
+export type {ViewSelectorWidgetProps} from './view-selector-widget';
+export type {GimbalWidgetProps} from './gimbal-widget';
+
+export {LightTheme, DarkTheme, LightGlassTheme, DarkGlassTheme} from './themes';
+export type {DeckWidgetTheme} from './themes';
+
+// Experimental exports
 
-export type {WidgetImplProps} from './widget-impl';
-export {WidgetImpl as _WidgetImpl} from './widget-impl';
-import * as _components from './components';
-export {_components};
+export {ButtonGroup as _ButtonGroup, type ButtonGroupProps} from './lib/components/button-group';
+export {IconButton as _IconButton, type IconButtonProps} from './lib/components/icon-button';
+export {
+  GroupedIconButton as _GroupedIconButton,
+  type GroupedIconButtonProps
+} from './lib/components/grouped-icon-button';
+export {
+  DropdownMenu as _DropdownMenu,
+  type DropdownMenuProps
+} from './lib/components/dropdown-menu';
+export {SimpleMenu as _SimpleMenu, type SimpleMenuProps} from './lib/components/simple-menu';
+export {IconMenu as _IconMenu, type IconMenuProps} from './lib/components/icon-menu';
 
-export * from './themes';
+// Experimental geocoders. May be removed, use at your own risk!
+export {type Geocoder} from './lib/geocode/geocoder';
+export {
+  GoogleGeocoder as _GoogleGeocoder,
+  MapboxGeocoder as _MapboxGeocoder,
+  OpenCageGeocoder as _OpenCageGeocoder,
+  CoordinatesGeocoder as _CoordinatesGeocoder,
+  CurrentLocationGeocoder as _CurrentLocationGeocoder
+} from './lib/geocode/geocoders';

package/src/info-widget.tsx

@@ -0,0 +1,225 @@
+/* global document */
+import {Widget, WidgetProps} from '@deck.gl/core';
+import type {Deck, PickingInfo, Viewport} from '@deck.gl/core';
+import {render, JSX} from 'preact';
+
+export type InfoWidgetProps = WidgetProps & {
+  /** View to attach to and interact with. Required when using multiple views. */
+  viewId?: string | null;
+  /** InfoWidget mode */
+  mode: 'click' | 'hover' | 'static';
+  /** Get the popup contents from the selected element */
+  getTooltip?: (info: PickingInfo, widget: InfoWidget) => any;
+  /** Position at which to place popup (clicked point: [longitude, latitude]). */
+  position: [number, number];
+  /** Text of popup */
+  text?: string;
+  /** Visibility of info widget */
+  visible?: boolean;
+  /** Minimum offset (in pixels) to keep the popup away from the canvas edges. */
+  minOffset?: number;
+  onClick?: (widget: InfoWidget, info: PickingInfo) => boolean;
+};
+
+export class InfoWidget extends Widget<InfoWidgetProps> {
+  static defaultProps: Required<InfoWidgetProps> = {
+    ...Widget.defaultProps,
+    position: [0, 0],
+    text: '',
+    visible: false,
+    // Set default minOffset if not provided
+    minOffset: 0,
+    viewId: null,
+    mode: 'hover',
+    getTooltip: undefined!,
+    onClick: undefined!
+  };
+
+  className = 'deck-widget-info';
+  placement = 'fill' as const;
+  viewId?: string | null = null;
+  viewport?: Viewport;
+
+  constructor(props: InfoWidgetProps) {
+    super(props, InfoWidget.defaultProps);
+    props.position = props.position || [0, 0];
+    props.text = props.text || '';
+    props.visible = props.visible || false;
+    // Set default minOffset if not provided
+    props.minOffset = props.minOffset ?? 0;
+  }
+
+  setProps(props: Partial<InfoWidgetProps>) {
+    super.setProps(props);
+  }
+
+  onViewportChange(viewport) {
+    this.viewport = viewport;
+    this.updateHTML();
+  }
+
+  onHover(info: PickingInfo): void {
+    if (this.props.mode === 'hover' && this.props.getTooltip) {
+      const tooltip = this.props.getTooltip(info, this);
+      // hover tooltips should show over static and click infos
+      this.setProps({
+        visible: tooltip !== null,
+        ...tooltip,
+        style: {zIndex: 1, ...tooltip?.style}
+      });
+    }
+  }
+
+  onClick(info: PickingInfo): boolean {
+    if (this.props.mode === 'click' && this.props.getTooltip) {
+      const tooltip = this.props.getTooltip(info, this);
+      this.setProps({
+        visible: tooltip !== null,
+        ...tooltip
+      });
+      return tooltip !== null;
+    }
+
+    // Original behavior
+    return this.props.onClick?.(this, info) || false;
+  }
+
+  // TODO - Align with onCreateRootElement
+  onAdd({deck, viewId}: {deck: Deck<any>; viewId: string | null}): HTMLDivElement {
+    const {className} = this.props;
+    const element = document.createElement('div');
+    element.classList.add('deck-widget', 'deck-widget-info');
+    if (className) element.classList.add(className);
+    // Ensure absolute positioning relative to the deck container
+    const style = {margin: '0px', top: '0px', left: '0px', position: 'absolute'};
+    Object.entries(style).forEach(([key, value]) => element.style.setProperty(key, value));
+    this.deck = deck;
+    if (!viewId) {
+      this.viewport = deck.getViewports()[0];
+    } else {
+      this.viewport = deck.getViewports().find(viewport => viewport.id === viewId);
+    }
+    this.rootElement = element;
+    this.updateHTML();
+    return element;
+  }
+
+  onRenderHTML(rootElement: HTMLElement): void {
+    if (!this.viewport) {
+      return;
+    }
+    const [longitude, latitude] = this.props.position;
+    // Project the clicked geographic coordinate to canvas (x, y)
+    const [x, y] = this.viewport.project([longitude, latitude]);
+
+    const minOffset = this.props.minOffset || 0;
+    const gap = 10; // gap between clicked point and popup box
+    const arrowHeight = 8; // height of the triangle arrow
+    const arrowWidth = 16; // full width of the arrow
+
+    // Decide vertical orientation.
+    // If the clicked point is in the bottom half, place the popup above the point.
+    const isAbove = y > this.viewport.height / 2;
+    const background = (this.props.style && this.props.style.background) || 'rgba(255,255,255,0.9)';
+
+    // Render the popup container with a content box and a placeholder for the arrow.
+    // The container is positioned absolutely (initially at 0,0) and will be repositioned after measuring.
+    const ui = this.props.visible ? (
+      <div className="popup-container" style={{position: 'absolute', left: 0, top: 0}}>
+        <div
+          className="popup-content"
+          style={{
+            background,
+            padding: '10px',
+            position: 'relative',
+            // Include any additional styles
+            ...(this.props.style as JSX.CSSProperties)
+          }}
+        >
+          {this.props.text}
+        </div>
+        <div className="popup-arrow" style={{position: 'absolute', width: '0px', height: '0px'}} />
+      </div>
+    ) : null;
+    render(ui, rootElement);
+
+    // After rendering, measure the content and adjust positioning so that:
+    // - The popup (with its arrow) does not cover the clicked point.
+    // - The arrow's tip points to the clicked point.
+    // - The popup remains within the canvas bounds, with minOffset.
+    // eslint-disable-next-line max-statements, complexity
+    requestAnimationFrame(() => {
+      if (!this.props.visible || !rootElement.firstChild || !this.viewport) return;
+
+      const container = rootElement.firstChild as HTMLElement;
+      const contentEl = container.querySelector('.popup-content') as HTMLElement;
+      const arrowEl = container.querySelector('.popup-arrow') as HTMLElement;
+      if (!contentEl || !arrowEl) return;
+      const contentRect = contentEl.getBoundingClientRect();
+      const popupWidth = contentRect.width;
+      const popupHeight = contentRect.height;
+
+      // Compute ideal horizontal position: center the popup on the clicked x
+      let computedLeft = x - popupWidth / 2;
+      // Compute vertical position based on orientation:
+      // If the popup is above, position its bottom edge (minus arrow & gap) at the clicked y.
+      // Otherwise, position its top edge (plus arrow & gap) at the clicked y.
+      let computedTop;
+      if (isAbove) {
+        computedTop = y - gap - arrowHeight - popupHeight;
+      } else {
+        computedTop = y + gap + arrowHeight;
+      }
+
+      // Ensure the popup (content) stays within horizontal bounds of the canvas
+      if (computedLeft < minOffset) {
+        computedLeft = minOffset;
+      }
+      if (computedLeft + popupWidth > this.viewport.width - minOffset) {
+        computedLeft = this.viewport.width - minOffset - popupWidth;
+      }
+
+      // Ensure the vertical position (including the arrow) stays within canvas bounds.
+      if (isAbove) {
+        if (computedTop < minOffset) {
+          computedTop = minOffset;
+        }
+      } else if (computedTop + popupHeight + arrowHeight > this.viewport.height - minOffset) {
+        computedTop = this.viewport.height - minOffset - popupHeight - arrowHeight;
+      }
+
+      // Update container position (remove any transform and set left/top explicitly)
+      container.style.left = `${computedLeft}px`;
+      container.style.top = `${computedTop}px`;
+      container.style.transform = '';
+
+      // Compute arrow's horizontal offset relative to the container.
+      // We want the arrow's tip to align with the clicked point.
+      let arrowLeft = x - computedLeft - arrowWidth / 2;
+      // Optionally constrain arrowLeft so it stays within the popup's width.
+      arrowLeft = Math.max(arrowLeft, 0);
+      arrowLeft = Math.min(arrowLeft, popupWidth - arrowWidth);
+
+      // Update arrow element's style based on orientation.
+      if (isAbove) {
+        // Popup is above the clicked point so arrow appears at the bottom of the popup.
+        arrowEl.style.left = `${arrowLeft}px`;
+        arrowEl.style.bottom = `-${arrowHeight}px`;
+        arrowEl.style.top = '';
+        arrowEl.style.borderLeft = `${arrowWidth / 2}px solid transparent`;
+        arrowEl.style.borderRight = `${arrowWidth / 2}px solid transparent`;
+        arrowEl.style.borderTop = `${arrowHeight}px solid ${background}`;
+        arrowEl.style.borderBottom = '';
+      } else {
+        // Popup is below the clicked point so arrow appears at the top.
+        arrowEl.style.left = `${arrowLeft}px`;
+        arrowEl.style.top = `-${arrowHeight}px`;
+        arrowEl.style.bottom = '';
+        arrowEl.style.borderLeft = `${arrowWidth / 2}px solid transparent`;
+        arrowEl.style.borderRight = `${arrowWidth / 2}px solid transparent`;
+        arrowEl.style.borderBottom = `${arrowHeight}px solid ${background}`;
+        arrowEl.style.borderTop = '';
+      }
+    });
+  }
+}

package/src/lib/components/button-group.tsx

@@ -0,0 +1,16 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ComponentChildren} from 'preact';
+
+export type ButtonGroupProps = {
+  children: ComponentChildren;
+  orientation;
+};
+
+/** Renders a group of buttons with Widget CSS */
+export const ButtonGroup = (props: ButtonGroupProps) => {
+  const {children, orientation} = props;
+  return <div className={`deck-widget-button-group ${orientation}`}>{children}</div>;
+};

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

@@ -0,0 +1,98 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {type JSX} from 'preact';
+import {useState, useRef, useEffect} from 'preact/hooks';
+
+export type DropdownMenuProps = {
+  menuItems: string[];
+  onSelect: (value: string) => void;
+  style?: JSX.CSSProperties;
+};
+
+export const DropdownMenu = (props: DropdownMenuProps) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+
+  const toggleDropdown = () => setIsOpen(!isOpen);
+
+  const handleClickOutside = (event: MouseEvent) => {
+    if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+      setIsOpen(false);
+    }
+  };
+
+  useEffect(() => {
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside);
+    };
+  }, []);
+
+  const handleSelect = (value: string) => {
+    props.onSelect(value);
+    setIsOpen(false);
+  };
+
+  return (
+    <div
+      className="dropdown-container"
+      ref={dropdownRef}
+      style={{
+        position: 'relative',
+        display: 'inline-block',
+        ...props.style
+      }}
+    >
+      <button
+        onClick={toggleDropdown}
+        style={{
+          width: '30px',
+          height: '30px',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          border: '1px solid #ccc',
+          borderRadius: '4px',
+          background: '#fff',
+          cursor: 'pointer',
+          padding: 0
+        }}
+      >
+        ▼
+      </button>
+      {isOpen && (
+        <ul
+          style={{
+            position: 'absolute',
+            top: '100%',
+            right: '100%',
+            background: '#fff',
+            border: '1px solid #ccc',
+            borderRadius: '4px',
+            listStyle: 'none',
+            padding: '4px 0',
+            margin: 0,
+            zIndex: 1000,
+            minWidth: '200px'
+          }}
+        >
+          {props.menuItems.map(item => (
+            <li
+              key={item}
+              onClick={() => handleSelect(item)}
+              style={{
+                padding: '4px 8px',
+                cursor: 'pointer',
+                whiteSpace: 'nowrap'
+              }}
+            >
+              {item}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+};

package/src/lib/components/grouped-icon-button.tsx

@@ -0,0 +1,24 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export type GroupedIconButtonProps = {
+  className?: string;
+  label: string;
+  onClick: () => void;
+};
+
+/** Renders an icon button as part of a ButtonGroup */
+export const GroupedIconButton = props => {
+  const {className, label, onClick} = props;
+  return (
+    <button
+      className={`deck-widget-icon-button ${className || ''}`}
+      type="button"
+      onClick={onClick}
+      title={label}
+    >
+      <div className="deck-widget-icon" />
+    </button>
+  );
+};

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

@@ -0,0 +1,30 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ComponentChildren} from 'preact';
+
+export type IconButtonProps = {
+  className: string;
+  label: string;
+  onClick: (event?) => unknown;
+  /** Optional icon or element to render inside the button */
+  children?: ComponentChildren;
+};
+
+/** Renders a button component with widget CSS */
+export const IconButton = (props: IconButtonProps) => {
+  const {className, label, onClick, children} = props;
+  return (
+    <div className="deck-widget-button">
+      <button
+        className={`deck-widget-icon-button ${className}`}
+        type="button"
+        onClick={onClick}
+        title={label}
+      >
+        {children ? children : <div className="deck-widget-icon" />}
+      </button>
+    </div>
+  );
+};