@deck.gl-community/widgets 9.2.0-beta.5

package/src/widgets/html-cluster-widget.ts

@@ -0,0 +1,84 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {point} from '@turf/helpers';
+import Supercluster from 'supercluster';
+import type {VNode} from 'preact';
+
+import type {WidgetProps, Viewport} from '@deck.gl/core';
+import {HtmlOverlayWidget, type HtmlOverlayWidgetProps} from './html-overlay-widget';
+
+export type HtmlClusterWidgetProps = HtmlOverlayWidgetProps & WidgetProps;
+
+export abstract class HtmlClusterWidget<ObjType> extends HtmlOverlayWidget<HtmlClusterWidgetProps> {
+  static override defaultProps = {
+    ...HtmlOverlayWidget.defaultProps,
+    id: 'html-cluster-overlay'
+  } satisfies Required<WidgetProps> & HtmlClusterWidgetProps;
+
+  protected superCluster: Supercluster | null = null;
+  protected lastObjects: ObjType[] | null = null;
+
+  protected override getOverlayItems(viewport: Viewport): VNode[] {
+    const newObjects = this.getAllObjects();
+    if (newObjects !== this.lastObjects) {
+      this.superCluster = new Supercluster(this.getClusterOptions());
+      this.superCluster.load(
+        newObjects.map((object) => point(this.getObjectCoordinates(object), {object}))
+      );
+      this.lastObjects = newObjects;
+    }
+
+    const clusters = this.superCluster?.getClusters([-180, -90, 180, 90], Math.round(this.getZoom())) ?? [];
+
+    const overlayItems = clusters.map(
+      ({
+        geometry: {coordinates},
+        properties: {cluster, point_count: pointCount, cluster_id: clusterId, object}
+      }) =>
+        cluster
+          ? this.renderCluster(coordinates, clusterId, pointCount)
+          : this.renderObject(coordinates, object)
+    );
+
+    return overlayItems.filter(Boolean) as VNode[];
+  }
+
+  getClusterObjects(clusterId: number): ObjType[] {
+    return (
+      this.superCluster
+        ?.getLeaves(clusterId, Infinity)
+        .map((leaf) => leaf.properties.object as ObjType) ?? []
+    );
+  }
+
+  // Override to provide items that need clustering.
+  // If the items have not changed please provide the same array to avoid
+  // regeneration of the cluster which causes performance issues.
+  abstract getAllObjects(): ObjType[];
+
+  // Override to provide coordinates for each object of getAllObjects()
+  abstract getObjectCoordinates(obj: ObjType): [number, number];
+
+  // Get options object used when instantiating supercluster
+  getClusterOptions(): Record<string, any> {
+    return {
+      maxZoom: 20
+    };
+  }
+
+  // Override to return an HtmlOverlayItem
+  abstract renderObject(
+    coordinates: number[],
+    obj: ObjType
+  ): VNode<Record<string, any>> | null | undefined;
+
+  // Override to return an HtmlOverlayItem
+  // use getClusterObjects() to get cluster contents
+  abstract renderCluster(
+    coordinates: number[],
+    clusterId: number,
+    pointCount: number
+  ): VNode<Record<string, any>> | null | undefined;
+}

package/src/widgets/html-overlay-item.tsx

@@ -0,0 +1,32 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ComponentChildren, JSX} from 'preact';
+
+export type HtmlOverlayItemProps = {
+  /** Injected by HtmlOverlayWidget */
+  x?: number;
+  /** Injected by HtmlOverlayWidget */
+  y?: number;
+
+  /** Coordinates of this overlay in [lng, lat] (and optional z). */
+  coordinates: number[];
+  children?: ComponentChildren;
+  style?: JSX.CSSProperties;
+};
+
+export function HtmlOverlayItem({x = 0, y = 0, children, style, ...props}: HtmlOverlayItemProps) {
+  const {zIndex = 'auto', ...remainingStyle} = style || {};
+
+  return (
+    // Using transform translate to position overlay items will result in a smooth zooming
+    // effect, whereas using the top/left css properties will cause overlay items to
+    // jiggle when zooming
+    <div style={{transform: `translate(${x}px, ${y}px)`, position: 'absolute', zIndex: `${zIndex}`}}>
+      <div style={{userSelect: 'none', ...remainingStyle}} {...props}>
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/widgets/html-overlay-widget.tsx

@@ -0,0 +1,147 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {cloneElement, render, toChildArray, Fragment, type ComponentChildren, type VNode} from 'preact';
+import type {Deck, Viewport, WidgetPlacement, WidgetProps} from '@deck.gl/core';
+import {Widget} from '@deck.gl/core';
+
+export type HtmlOverlayWidgetProps = WidgetProps & {
+  /** View id to attach the overlay to. Defaults to the containing view. */
+  viewId?: string | null;
+  /** Margin beyond the viewport before hiding overlay items. */
+  overflowMargin?: number;
+  /** z-index for the overlay container. */
+  zIndex?: number;
+  /** Items to render; defaults to the supplied children. */
+  items?: ComponentChildren;
+};
+
+const ROOT_STYLE: Partial<CSSStyleDeclaration> = {
+  width: '100%',
+  height: '100%',
+  position: 'absolute',
+  pointerEvents: 'none',
+  overflow: 'hidden'
+};
+
+export class HtmlOverlayWidget<PropsT extends HtmlOverlayWidgetProps = HtmlOverlayWidgetProps> extends Widget<PropsT> {
+  static override defaultProps = {
+    id: 'html-overlay',
+    viewId: null,
+    overflowMargin: 0,
+    zIndex: 1,
+    style: {},
+    className: ''
+  } satisfies Required<WidgetProps> &
+    Required<Pick<HtmlOverlayWidgetProps, 'overflowMargin' | 'zIndex'>> &
+    HtmlOverlayWidgetProps;
+
+  placement: WidgetPlacement = 'fill';
+  className = 'deck-widget-html-overlay';
+  deck?: Deck | null = null;
+  protected viewport: Viewport | null = null;
+
+  constructor(props: PropsT = {} as PropsT) {
+    super({...HtmlOverlayWidget.defaultProps, ...props});
+    this.viewId = props.viewId ?? null;
+  }
+
+  override setProps(props: Partial<PropsT>): void {
+    if (props.viewId !== undefined) {
+      this.viewId = props.viewId;
+    }
+    super.setProps(props);
+  }
+
+  override onAdd({deck, viewId}: {deck: Deck; viewId: string | null}): void {
+    this.deck = deck;
+    if (this.viewId === undefined) {
+      this.viewId = viewId;
+    }
+  }
+
+  override onRemove(): void {
+    this.deck = null;
+    this.viewport = null;
+  }
+
+  override onViewportChange(viewport: Viewport): void {
+    if (!this.viewId || this.viewId === viewport.id) {
+      this.viewport = viewport;
+      this.updateHTML();
+    }
+  }
+
+  protected getViewport(): Viewport | null {
+    return this.viewport;
+  }
+
+  protected getZoom(): number {
+    return this.viewport?.zoom ?? 0;
+  }
+
+  protected scaleWithZoom(n: number): number {
+    return n / Math.pow(2, 20 - this.getZoom());
+  }
+
+  protected breakpointWithZoom<T>(threshold: number, a: T, b: T): T {
+    return this.getZoom() > threshold ? a : b;
+  }
+
+  protected getCoords(viewport: Viewport, coordinates: number[]): [number, number] {
+    const pos = viewport.project(coordinates);
+    if (!pos) return [-1, -1];
+    return pos as [number, number];
+  }
+
+  protected inView(viewport: Viewport, [x, y]: number[]): boolean {
+    const overflowMargin = this.props.overflowMargin ?? 0;
+    const {width, height} = viewport;
+    return !(
+      x < -overflowMargin ||
+      y < -overflowMargin ||
+      x > width + overflowMargin ||
+      y > height + overflowMargin
+    );
+  }
+
+  protected getOverlayItems(viewport: Viewport): VNode[] {
+    const {items} = this.props;
+    return (items ? toChildArray(items) : []) as VNode[];
+  }
+
+  protected projectItems(items: VNode[], viewport: Viewport): VNode[] {
+    const renderItems: VNode[] = [];
+    items
+      .filter(Boolean)
+      .forEach((item, index) => {
+        const coordinates = (item.props as any)?.coordinates;
+        if (!coordinates) {
+          return;
+        }
+        const [x, y] = this.getCoords(viewport, coordinates);
+        if (this.inView(viewport, [x, y])) {
+          const key = item.key === null || item.key === undefined ? index : item.key;
+          renderItems.push(cloneElement(item, {x, y, key}));
+        }
+      });
+
+    return renderItems;
+  }
+
+  override onRenderHTML(rootElement: HTMLElement): void {
+    Object.assign(rootElement.style, ROOT_STYLE, {zIndex: `${this.props.zIndex ?? 1}`});
+
+    const viewport = this.getViewport();
+    if (!viewport) {
+      render(null, rootElement);
+      return;
+    }
+
+    const overlayItems = this.getOverlayItems(viewport);
+    const renderedItems = this.projectItems(overlayItems, viewport);
+
+    render(<Fragment>{renderedItems}</Fragment>, rootElement);
+  }
+}

package/src/widgets/html-tooltip-widget.tsx

@@ -0,0 +1,93 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ComponentChildren, VNode} from 'preact';
+import type {PickingInfo, WidgetProps, Viewport} from '@deck.gl/core';
+import {HtmlOverlayItem} from './html-overlay-item';
+import {HtmlOverlayWidget, type HtmlOverlayWidgetProps} from './html-overlay-widget';
+
+export type HtmlTooltipWidgetProps = HtmlOverlayWidgetProps & {
+  /** Delay before showing the tooltip (ms). */
+  showDelay?: number;
+  /** Extract a tooltip string or node from picking info. */
+  getTooltip?: (pickingInfo: PickingInfo) => ComponentChildren;
+};
+
+const TOOLTIP_STYLE = {
+  transform: 'translate(-50%,-100%)',
+  backgroundColor: 'rgba(0, 0, 0, 0.3)',
+  padding: '4px 8px',
+  borderRadius: 8,
+  color: 'white'
+};
+
+const SHOW_TOOLTIP_TIMEOUT = 250;
+
+function defaultGetTooltip(pickingInfo: PickingInfo): ComponentChildren {
+  return pickingInfo.object?.style?.tooltip;
+}
+
+export class HtmlTooltipWidget extends HtmlOverlayWidget<HtmlTooltipWidgetProps> {
+  static override defaultProps = {
+    ...HtmlOverlayWidget.defaultProps,
+    id: 'html-tooltip-overlay',
+    showDelay: SHOW_TOOLTIP_TIMEOUT,
+    getTooltip: defaultGetTooltip
+  } satisfies Required<WidgetProps> & Required<Pick<HtmlTooltipWidgetProps, 'showDelay' | 'getTooltip'>> &
+    HtmlTooltipWidgetProps;
+
+  private timeoutID: ReturnType<typeof globalThis.setTimeout> | null = null;
+  private pickingInfo: PickingInfo | null = null;
+  private visible = false;
+
+  override onRemove(): void {
+    if (this.timeoutID !== null) {
+      globalThis.clearTimeout(this.timeoutID);
+      this.timeoutID = null;
+    }
+    this.visible = false;
+    this.pickingInfo = null;
+  }
+
+  override onHover(pickingInfo: PickingInfo): void {
+    if (this.timeoutID !== null) {
+      globalThis.clearTimeout(this.timeoutID);
+      this.timeoutID = null;
+    }
+
+    const tooltipContent = this.props.getTooltip?.(pickingInfo);
+
+    if (pickingInfo && tooltipContent) {
+      const delay = this.props.showDelay ?? SHOW_TOOLTIP_TIMEOUT;
+      this.timeoutID = globalThis.setTimeout(() => {
+        this.visible = true;
+        this.pickingInfo = pickingInfo;
+        this.updateHTML();
+      }, delay);
+    } else {
+      this.visible = false;
+      this.pickingInfo = null;
+      this.updateHTML();
+    }
+  }
+
+  protected override getOverlayItems(viewport: Viewport): VNode[] {
+    if (!this.visible || !this.pickingInfo) {
+      return [];
+    }
+
+    const tooltipContent = this.props.getTooltip?.(this.pickingInfo);
+    const coordinates =
+      this.pickingInfo.coordinate ?? (this.pickingInfo as Partial<{lngLat: number[]}>).lngLat ?? null;
+    if (!tooltipContent || !coordinates) {
+      return [];
+    }
+
+    return [
+      <HtmlOverlayItem key="tooltip" coordinates={coordinates} style={TOOLTIP_STYLE}>
+        {tooltipContent}
+      </HtmlOverlayItem>
+    ];
+  }
+}

package/src/widgets/long-press-button.tsx

@@ -0,0 +1,125 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Component, type ComponentChildren} from 'preact';
+
+const REPEAT_DELAY_MS = 300;
+const REPEAT_INTERVAL_MS = 100;
+
+export type LongPressButtonProps = {
+  onClick: () => void;
+  children: ComponentChildren;
+};
+
+export class LongPressButton extends Component<LongPressButtonProps> {
+  buttonPressTimer: ReturnType<typeof setTimeout> | null = null;
+  usingPointerEvents = false;
+
+  private stopEvent(event: Event) {
+    event.stopPropagation();
+    if (typeof (event as any).stopImmediatePropagation === 'function') {
+      (event as any).stopImmediatePropagation();
+    }
+    if (typeof (event as any).preventDefault === 'function') {
+      (event as any).preventDefault();
+    }
+  }
+
+  private repeat = () => {
+    if (this.buttonPressTimer) {
+      this.props.onClick();
+      this.buttonPressTimer = setTimeout(this.repeat, REPEAT_INTERVAL_MS);
+    }
+  };
+
+  private startPress(event: Event) {
+    this.stopEvent(event);
+    this.props.onClick();
+    this.buttonPressTimer = setTimeout(this.repeat, REPEAT_DELAY_MS);
+  }
+
+  private endPress(event?: Event) {
+    if (event) {
+      this.stopEvent(event);
+    }
+    if (this.buttonPressTimer) {
+      clearTimeout(this.buttonPressTimer);
+    }
+    this.buttonPressTimer = null;
+  }
+
+  private handlePointerDown = (event: PointerEvent) => {
+    this.usingPointerEvents = true;
+    (event.currentTarget as HTMLElement | null)?.setPointerCapture?.(event.pointerId);
+    this.startPress(event);
+  };
+
+  private handlePointerUp = (event: PointerEvent) => {
+    (event.currentTarget as HTMLElement | null)?.releasePointerCapture?.(event.pointerId);
+    this.endPress(event);
+  };
+
+  private handlePointerCancel = (event: PointerEvent) => {
+    (event.currentTarget as HTMLElement | null)?.releasePointerCapture?.(event.pointerId);
+    this.endPress(event);
+  };
+
+  private handleMouseDown = (event: MouseEvent) => {
+    if (this.usingPointerEvents) {
+      return;
+    }
+    this.startPress(event);
+    document.addEventListener('mouseup', this.handleMouseUp, {once: true});
+  };
+
+  private handleMouseUp = (event: MouseEvent) => {
+    if (this.usingPointerEvents) {
+      return;
+    }
+    this.endPress(event);
+  };
+
+  private handleTouchStart = (event: TouchEvent) => {
+    if (this.usingPointerEvents) {
+      return;
+    }
+    this.startPress(event);
+    document.addEventListener('touchend', this.handleTouchEnd, {once: true});
+    document.addEventListener('touchcancel', this.handleTouchEnd, {once: true});
+  };
+
+  private handleTouchEnd = (event: TouchEvent) => {
+    if (this.usingPointerEvents) {
+      return;
+    }
+    this.endPress(event);
+  };
+
+  render() {
+    return (
+      <div className="deck-widget-button">
+        <div
+          style={{pointerEvents: 'auto'}}
+          onPointerDown={this.handlePointerDown}
+          onPointerUp={this.handlePointerUp}
+          onPointerCancel={this.handlePointerCancel}
+          onPointerMove={(event) => this.stopEvent(event)}
+          onPointerLeave={this.handlePointerCancel}
+          onPointerOut={this.handlePointerCancel}
+          onMouseDown={this.handleMouseDown}
+          onMouseUp={this.handleMouseUp}
+          onMouseMove={(event) => this.stopEvent(event)}
+          onTouchStart={this.handleTouchStart}
+          onTouchEnd={this.handleTouchEnd}
+          onTouchMove={(event) => this.stopEvent(event)}
+          onContextMenu={(event) => event.preventDefault()}
+          onWheel={(event) => this.stopEvent(event)}
+          onClick={(event) => this.stopEvent(event)}
+        >
+          {this.props.children}
+        </div>
+      </div>
+    );
+  }
+}

package/src/widgets/long-press-controller.ts

@@ -0,0 +1,159 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/* eslint-disable @typescript-eslint/unbound-method */
+
+const REPEAT_DELAY_MS = 300;
+const REPEAT_INTERVAL_MS = 100;
+
+/**
+ * Utility that attaches pointer/mouse/touch handlers to an element and
+ * invokes a callback immediately plus while the interaction is held.
+ */
+export class LongPressController {
+  private buttonPressTimer: ReturnType<typeof setTimeout> | null = null;
+  private usingPointerEvents = false;
+
+  constructor(private element: HTMLElement, private onActivate: () => void) {
+    this.handlePointerDown = this.handlePointerDown.bind(this);
+    this.handlePointerUp = this.handlePointerUp.bind(this);
+    this.handlePointerCancel = this.handlePointerCancel.bind(this);
+    this.handleMouseDown = this.handleMouseDown.bind(this);
+    this.handleMouseUp = this.handleMouseUp.bind(this);
+    this.handleMouseMove = this.handleMouseMove.bind(this);
+    this.handleTouchStart = this.handleTouchStart.bind(this);
+    this.handleTouchEnd = this.handleTouchEnd.bind(this);
+    this.handleTouchMove = this.handleTouchMove.bind(this);
+
+    element.addEventListener('pointerdown', this.handlePointerDown);
+    element.addEventListener('pointerup', this.handlePointerUp);
+    element.addEventListener('pointercancel', this.handlePointerCancel);
+    element.addEventListener('pointerleave', this.handlePointerCancel);
+    element.addEventListener('pointerout', this.handlePointerCancel);
+    element.addEventListener('pointermove', this.handlePointerMove);
+    element.addEventListener('mousedown', this.handleMouseDown);
+    element.addEventListener('mousemove', this.handleMouseMove);
+    element.addEventListener('touchstart', this.handleTouchStart, {passive: false});
+    element.addEventListener('touchend', this.handleTouchEnd, {passive: false});
+    element.addEventListener('touchcancel', this.handleTouchEnd, {passive: false});
+    element.addEventListener('touchmove', this.handleTouchMove, {passive: false});
+    element.addEventListener('contextmenu', (event) => event.preventDefault());
+    element.addEventListener('wheel', (event) => this.stopEvent(event));
+    element.addEventListener('click', (event) => this.stopEvent(event));
+  }
+
+  destroy(): void {
+    this.endPress();
+    this.element.removeEventListener('pointerdown', this.handlePointerDown);
+    this.element.removeEventListener('pointerup', this.handlePointerUp);
+    this.element.removeEventListener('pointercancel', this.handlePointerCancel);
+    this.element.removeEventListener('pointerleave', this.handlePointerCancel);
+    this.element.removeEventListener('pointerout', this.handlePointerCancel);
+    this.element.removeEventListener('pointermove', this.handlePointerMove);
+    this.element.removeEventListener('mousedown', this.handleMouseDown);
+    this.element.removeEventListener('mousemove', this.handleMouseMove);
+    this.element.removeEventListener('touchstart', this.handleTouchStart);
+    this.element.removeEventListener('touchend', this.handleTouchEnd);
+    this.element.removeEventListener('touchcancel', this.handleTouchEnd);
+    this.element.removeEventListener('touchmove', this.handleTouchMove);
+  }
+
+  private repeat = () => {
+    if (this.buttonPressTimer) {
+      this.onActivate();
+      this.buttonPressTimer = setTimeout(this.repeat, REPEAT_INTERVAL_MS);
+    }
+  };
+
+  private startPress(event: Event) {
+    this.stopEvent(event);
+    this.onActivate();
+    this.buttonPressTimer = setTimeout(this.repeat, REPEAT_DELAY_MS);
+  }
+
+  private endPress(event?: Event) {
+    if (event) {
+      this.stopEvent(event);
+    }
+    if (this.buttonPressTimer) {
+      clearTimeout(this.buttonPressTimer);
+      this.buttonPressTimer = null;
+    }
+  }
+
+  private handlePointerDown(event: PointerEvent) {
+    this.usingPointerEvents = true;
+    (event.currentTarget as HTMLElement | null)?.setPointerCapture?.(event.pointerId);
+    this.startPress(event);
+  }
+
+  private handlePointerUp(event: PointerEvent) {
+    (event.currentTarget as HTMLElement | null)?.releasePointerCapture?.(event.pointerId);
+    this.endPress(event);
+  }
+
+  private handlePointerCancel(event: PointerEvent) {
+    (event.currentTarget as HTMLElement | null)?.releasePointerCapture?.(event.pointerId);
+    this.endPress(event);
+  }
+
+  private handlePointerMove = (event: Event) => {
+    this.stopEvent(event);
+  };
+
+  private handleMouseDown(event: MouseEvent) {
+    if (this.usingPointerEvents) {
+      return;
+    }
+    this.startPress(event);
+    document.addEventListener('mouseup', this.handleMouseUp, {once: true});
+  }
+
+  private handleMouseUp(event: MouseEvent) {
+    if (this.usingPointerEvents) {
+      return;
+    }
+    this.endPress(event);
+  }
+
+  private handleMouseMove(event: MouseEvent) {
+    if (this.usingPointerEvents) {
+      return;
+    }
+    this.stopEvent(event);
+  }
+
+  private handleTouchStart(event: TouchEvent) {
+    if (this.usingPointerEvents) {
+      return;
+    }
+    this.startPress(event);
+    document.addEventListener('touchend', this.handleTouchEnd, {once: true});
+    document.addEventListener('touchcancel', this.handleTouchEnd, {once: true});
+  }
+
+  private handleTouchEnd(event: TouchEvent) {
+    if (this.usingPointerEvents) {
+      return;
+    }
+    this.endPress(event);
+  }
+
+  private handleTouchMove(event: TouchEvent) {
+    if (this.usingPointerEvents) {
+      return;
+    }
+    this.stopEvent(event);
+  }
+
+  private stopEvent(event: Event) {
+    event.stopPropagation();
+    if (typeof (event as any).stopImmediatePropagation === 'function') {
+      (event as any).stopImmediatePropagation();
+    }
+    if (typeof (event as any).preventDefault === 'function') {
+      event.preventDefault();
+    }
+  }
+}