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

package/src/scale-widget.tsx

@@ -0,0 +1,183 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {WidgetPlacement, Viewport} from '@deck.gl/core';
+import {render} from 'preact';
+import {Widget, WidgetProps} from '@deck.gl/core';
+
+export type ScaleWidgetProps = WidgetProps & {
+  placement?: WidgetPlacement;
+  label?: string;
+  onCapture?: (widget: ScaleWidget) => void;
+};
+
+/**
+ * A scale widget that displays a Google Maps–like scale indicator.
+ * Instead of text inside a div, this widget renders an SVG that contains a horizontal line
+ * with two vertical tick marks (extending upward from the line only) and a pretty distance label
+ * positioned to the left of the line. The horizontal line’s length is computed from a “nice”
+ * candidate distance (e.g. 200, 500, 1000 m, etc.) so that its pixel width is between 100 and 200.
+ */
+export class ScaleWidget extends Widget<ScaleWidgetProps> {
+  static defaultProps: Required<ScaleWidgetProps> = {
+    ...Widget.defaultProps,
+    id: 'scale',
+    placement: 'bottom-left',
+    label: 'Scale',
+    onCapture: undefined!
+  };
+
+  className = 'deck-widget-scale';
+  placement: WidgetPlacement = 'bottom-left';
+
+  // The pixel width of the scale line (computed from a candidate distance)
+  scaleWidth: number = 10;
+  // The candidate distance (in meters) corresponding to the scale line length.
+  scaleValue: number = 0;
+  // The formatted distance label (e.g. "200 m" or "1.0 km")
+  scaleText: string = '';
+
+  constructor(props: ScaleWidgetProps = {}) {
+    super(props, ScaleWidget.defaultProps);
+    this.placement = props.placement ?? this.placement;
+  }
+
+  setProps(props: Partial<ScaleWidgetProps>): void {
+    this.placement = props.placement ?? this.placement;
+    super.setProps(props);
+  }
+
+  onRenderHTML(rootElement: HTMLElement): void {
+    // Reserve space for the text label (to the left of the horizontal line)
+    const lineOffsetX = 50;
+    // Overall SVG width includes the left offset plus the computed scale line width.
+    const svgWidth = lineOffsetX + this.scaleWidth;
+    const tickHeight = 10; // vertical tick extends upward by 10 pixels from the horizontal line
+    render(
+      <svg
+        className="deck-widget-scale"
+        width={svgWidth}
+        height={30}
+        style={{overflow: 'visible', background: 'transparent'}}
+        onClick={this.handleClick.bind(this)}
+      >
+        {/* Pretty distance label positioned to the left of the horizontal line */}
+        <text
+          x={lineOffsetX + 5}
+          y="10"
+          textAnchor="end"
+          alignmentBaseline="middle"
+          style={{fontSize: '16px', fill: 'black', fontWeight: 'bold', fontFamily: 'sans-serif'}}
+        >
+          {this.scaleText}
+        </text>
+        {/* Horizontal line */}
+        <line
+          x1={lineOffsetX}
+          y1="15"
+          x2={lineOffsetX + this.scaleWidth}
+          y2="15"
+          stroke="black"
+          strokeWidth="6"
+        />
+        {/* Left vertical tick (extending upward from the horizontal line) */}
+        <line
+          x1={lineOffsetX}
+          y1="15"
+          x2={lineOffsetX}
+          y2={15 - tickHeight}
+          stroke="black"
+          strokeWidth="6"
+        />
+        {/* Right vertical tick (extending upward from the horizontal line) */}
+        <line
+          x1={lineOffsetX + this.scaleWidth}
+          y1="15"
+          x2={lineOffsetX + this.scaleWidth}
+          y2={15 - tickHeight}
+          stroke="black"
+          strokeWidth="6"
+        />
+      </svg>,
+      rootElement
+    );
+  }
+
+  onViewportChange(viewport: Viewport): void {
+    // Only handle geospatial viewports (which contain latitude)
+    if (!('latitude' in viewport)) return;
+
+    const {latitude, zoom} = viewport as {latitude: number; zoom: number};
+    const metersPerPixel = getMetersPerPixel(latitude, zoom);
+    const {candidate, candidatePixels} = computeScaleCandidate(metersPerPixel);
+
+    this.scaleValue = candidate;
+    this.scaleWidth = candidatePixels;
+    // Format the candidate distance for display (using km if >= 1000 m)
+    if (candidate >= 1000) {
+      this.scaleText = `${(candidate / 1000).toFixed(1)} km`;
+    } else {
+      this.scaleText = `${candidate} m`;
+    }
+    this.updateHTML();
+  }
+
+  handleClick(): void {}
+}
+
+/**
+ * Compute the meters per pixel at a given latitude and zoom level.
+ *
+ * @param latitude - The current latitude.
+ * @param zoom - The current zoom level.
+ * @returns The number of meters per pixel.
+ */
+function getMetersPerPixel(latitude: number, zoom: number): number {
+  const earthCircumference = 40075016.686;
+  return (earthCircumference * Math.cos((latitude * Math.PI) / 180)) / Math.pow(2, zoom + 8);
+}
+
+/**
+ * Compute a "nice" scale candidate such that the scale bar width in pixels is between 100 and 200.
+ * The candidate distance (in meters) will be one of a set of round numbers (100, 200, 500, 1000, 2000, 5000, etc.).
+ *
+ * @param metersPerPixel - The number of meters per pixel at the current zoom/latitude.
+ * @returns An object containing the candidate distance and its width in pixels.
+ */
+function computeScaleCandidate(metersPerPixel: number): {
+  candidate: number;
+  candidatePixels: number;
+} {
+  const minPixels = 100;
+  const maxPixels = 200;
+  const targetPixels = (minPixels + maxPixels) / 2;
+  const targetDistance = targetPixels * metersPerPixel;
+
+  const exponent = Math.floor(Math.log10(targetDistance));
+  const base = Math.pow(10, exponent);
+  const multipliers = [1, 2, 5];
+
+  let candidate = multipliers[0] * base;
+  let candidatePixels = candidate / metersPerPixel;
+
+  for (let i = 0; i < multipliers.length; i++) {
+    const currentCandidate = multipliers[i] * base;
+    const currentPixels = currentCandidate / metersPerPixel;
+    if (currentPixels >= minPixels && currentPixels <= maxPixels) {
+      candidate = currentCandidate;
+      candidatePixels = currentPixels;
+      break;
+    }
+    if (currentPixels > maxPixels) {
+      candidate = i > 0 ? multipliers[i - 1] * base : currentCandidate;
+      candidatePixels = candidate / metersPerPixel;
+      break;
+    }
+    if (i === multipliers.length - 1 && currentPixels < minPixels) {
+      candidate = multipliers[0] * base * 10;
+      candidatePixels = candidate / metersPerPixel;
+    }
+  }
+  return {candidate, candidatePixels};
+}

package/src/screenshot-widget.tsx

@@ -3,13 +3,13 @@
 // Copyright (c) vis.gl contributors
 
 /* global document */
-import {WidgetImpl, WidgetImplProps} from './widget-impl';
-import {h, render} from 'preact';
-import {IconButton} from './components';
 import type {WidgetPlacement} 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 ScreenshotWidget */
-export type ScreenshotWidgetProps = WidgetImplProps & {
+export type ScreenshotWidgetProps = WidgetProps & {
   /** Widget positioning within the view. Default 'top-left'. */
   placement?: WidgetPlacement;
   /** Tooltip message */
@@ -26,9 +26,9 @@ export type ScreenshotWidgetProps = WidgetImplProps & {
  * A button widget that captures a screenshot of the current canvas and downloads it as a (png) file.
  * @note only captures canvas contents, not HTML DOM or CSS styles
  */
-export class ScreenshotWidget extends WidgetImpl<ScreenshotWidgetProps> {
+export class ScreenshotWidget extends Widget<ScreenshotWidgetProps> {
   static defaultProps: Required<ScreenshotWidgetProps> = {
-    ...WidgetImpl.defaultProps,
+    ...Widget.defaultProps,
     id: 'screenshot',
     placement: 'top-left',
     label: 'Screenshot',
@@ -41,7 +41,7 @@ export class ScreenshotWidget extends WidgetImpl<ScreenshotWidgetProps> {
   placement: WidgetPlacement = 'top-left';
 
   constructor(props: ScreenshotWidgetProps = {}) {
-    super({...ScreenshotWidget.defaultProps, ...props});
+    super(props, ScreenshotWidget.defaultProps);
     this.placement = props.placement ?? this.placement;
   }
 
@@ -50,16 +50,14 @@ export class ScreenshotWidget extends WidgetImpl<ScreenshotWidgetProps> {
     super.setProps(props);
   }
 
-  onRenderHTML() {
-    const element = this.element;
-    if (!element) return;
+  onRenderHTML(rootElement: HTMLElement): void {
     render(
       <IconButton
         className="deck-widget-camera"
         label={this.props.label}
         onClick={this.handleClick.bind(this)}
       />,
-      element
+      rootElement
     );
   }
 

package/src/splitter-widget.tsx

@@ -0,0 +1,179 @@
+// SplitterWidget.tsx
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {h, render} from 'preact';
+import {useState, useRef} from 'preact/hooks';
+import {Widget, WidgetProps} from '@deck.gl/core';
+
+/** Properties for the SplitterWidget */
+export type SplitterWidgetProps = WidgetProps & {
+  /** The view id for the first (resizable) view */
+  viewId1: string;
+  /** The view id for the second view */
+  viewId2: string;
+  /** Orientation of the splitter: vertical (default) or horizontal */
+  orientation?: 'vertical' | 'horizontal';
+  /** The initial split percentage (0 to 1) for the first view, default 0.5 */
+  initialSplit?: number;
+  /** Callback invoked when the splitter is dragged with the new split value */
+  onChange?: (newSplit: number) => void;
+  /** Callback invoked when dragging starts */
+  onDragStart?: () => void;
+  /** Callback invoked when dragging ends */
+  onDragEnd?: () => void;
+};
+
+/**
+ * A draggable splitter widget that appears as a vertical or horizontal line
+ * across the deck.gl canvas. It positions itself based on the split percentage
+ * of the first view and provides callbacks when dragged.
+ */
+export class SplitterWidget extends Widget<SplitterWidgetProps> {
+  static defaultProps: Required<SplitterWidgetProps> = {
+    ...Widget.defaultProps,
+    id: 'splitter-widget',
+    viewId1: '',
+    viewId2: '',
+    orientation: 'vertical',
+    initialSplit: 0.5,
+    onChange: () => {},
+    onDragStart: () => {},
+    onDragEnd: () => {}
+  };
+
+  className = 'deck-widget-splitter';
+  placement = 'fill' as const;
+
+  constructor(props: SplitterWidgetProps) {
+    // No placement prop is used.
+    super(props, SplitterWidget.defaultProps);
+  }
+
+  setProps(props: Partial<SplitterWidgetProps>) {
+    super.setProps(props);
+  }
+
+  onRenderHTML(rootElement: HTMLElement): void {
+    // Ensure the widget container fills the deck.gl canvas.
+    // TODO - Move styling to CSS
+    rootElement.style.position = 'absolute';
+    rootElement.style.top = '0';
+    rootElement.style.left = '0';
+    rootElement.style.width = '100%';
+    rootElement.style.height = '100%';
+    rootElement.style.margin = '0px';
+
+    render(
+      <Splitter
+        orientation={this.props.orientation}
+        initialSplit={this.props.initialSplit}
+        onChange={this.props.onChange}
+        onDragStart={this.props.onDragStart}
+        onDragEnd={this.props.onDragEnd}
+      />,
+      rootElement
+    );
+  }
+}
+
+/**
+ * A functional component that renders a draggable splitter line.
+ * It computes its position based on the provided split percentage and
+ * updates it during mouse drag events.
+ */
+function Splitter({
+  orientation,
+  initialSplit,
+  onChange,
+  onDragStart,
+  onDragEnd
+}: {
+  orientation: 'vertical' | 'horizontal';
+  initialSplit: number;
+  onChange?: (newSplit: number) => void;
+  onDragStart?: () => void;
+  onDragEnd?: () => void;
+}) {
+  const [split, setSplit] = useState(initialSplit);
+  const dragging = useRef(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const handleDragStart = (event: MouseEvent) => {
+    dragging.current = true;
+    onDragStart?.();
+    document.addEventListener('mousemove', handleDragging);
+    document.addEventListener('mouseup', handleDragEnd);
+    event.preventDefault();
+  };
+
+  const handleDragging = (event: MouseEvent) => {
+    if (!dragging.current || !containerRef.current) return;
+    const rect = containerRef.current.getBoundingClientRect();
+    let newSplit: number;
+    if (orientation === 'vertical') {
+      newSplit = (event.clientX - rect.left) / rect.width;
+    } else {
+      newSplit = (event.clientY - rect.top) / rect.height;
+    }
+    // Clamp newSplit between 5% and 95%
+    newSplit = Math.min(Math.max(newSplit, 0.05), 0.95);
+    setSplit(newSplit);
+    onChange?.(newSplit);
+  };
+
+  const handleDragEnd = (event: MouseEvent) => {
+    if (!dragging.current) return;
+    dragging.current = false;
+    onDragEnd?.();
+    document.removeEventListener('mousemove', handleDragging);
+    document.removeEventListener('mouseup', handleDragEnd);
+  };
+
+  // The splitter line style based on orientation and the current split percentage.
+  const splitterStyle: h.JSX.CSSProperties =
+    orientation === 'vertical'
+      ? {
+          position: 'absolute',
+          top: 0,
+          bottom: 0,
+          left: `${split * 100}%`,
+          width: '4px',
+          cursor: 'col-resize',
+          background: '#ccc',
+          zIndex: 10,
+          pointerEvents: 'auto',
+          boxShadow: 'inset -1px 0 0 white, inset 1px 0 0 white'
+        }
+      : {
+          position: 'absolute',
+          left: 0,
+          right: 0,
+          top: `${split * 100}%`,
+          height: '4px',
+          cursor: 'row-resize',
+          background: '#ccc',
+          zIndex: 10,
+          pointerEvents: 'auto',
+          boxShadow: 'inset -1px 0 0 white, inset 1px 0 0 white'
+        };
+
+  // Container style to fill the entire deck.gl canvas.
+  const containerStyle: h.JSX.CSSProperties = {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0
+  };
+
+  return (
+    <div ref={containerRef} style={containerStyle}>
+      <div
+        style={splitterStyle}
+        onMouseDown={handleDragStart as h.JSX.MouseEventHandler<HTMLElement>} // Use the appropriate Preact event type.
+      />
+    </div>
+  );
+}

package/src/stats-widget.tsx

@@ -0,0 +1,166 @@
+import {Widget, WidgetPlacement, WidgetProps} from '@deck.gl/core';
+import {luma} from '@luma.gl/core';
+import {render} from 'preact';
+import type {Stats, Stat} from '@probe.gl/stats';
+
+const RIGHT_ARROW = '\u25b6';
+const DOWN_ARROW = '\u2b07';
+
+const DEFAULT_COUNT_FORMATTER = (stat: Stat): string => `${stat.name}: ${stat.count}`;
+
+function formatTime(time: number): string {
+  return time < 1000 ? `${time.toFixed(2)}ms` : `${(time / 1000).toFixed(2)}s`;
+}
+
+function formatMemory(bytes: number): string {
+  const mb = bytes / 1e6;
+  return `${mb.toFixed(1)} MB`;
+}
+
+export const DEFAULT_FORMATTERS: Record<string, (stat: Stat) => string> = {
+  count: DEFAULT_COUNT_FORMATTER,
+  averageTime: (stat: Stat) => `${stat.name}: ${formatTime(stat.getAverageTime())}`,
+  totalTime: (stat: Stat) => `${stat.name}: ${formatTime(stat.time)}`,
+  fps: (stat: Stat) => `${stat.name}: ${Math.round(stat.getHz())}fps`,
+  memory: (stat: Stat) => `${stat.name}: ${formatMemory(stat.count)}`
+};
+
+export type StatsWidgetProps = WidgetProps & {
+  type?: 'deck' | 'luma' | 'device' | 'custom';
+  /** Stats object to visualize. */
+  stats?: Stats;
+  /** Title shown in the header of the pop-up. Defaults to stats.id. */
+  title?: string;
+  /** How many redraws to wait between updates. */
+  framesPerUpdate?: number;
+  /** Custom formatters for stat values. */
+  formatters?: Record<string, string | ((stat: Stat) => string)>;
+  /** Whether to reset particular stats after each update. */
+  resetOnUpdate?: Record<string, boolean>;
+};
+
+/** Displays probe.gl stats in a floating pop-up. */
+export class StatsWidget extends Widget<StatsWidgetProps> {
+  static defaultProps: Required<StatsWidgetProps> = {
+    ...Widget.defaultProps,
+    type: 'deck',
+    stats: undefined!,
+    title: 'Stats',
+    framesPerUpdate: 1,
+    formatters: {},
+    resetOnUpdate: {},
+    id: 'stats'
+  };
+
+  className = 'deck-widget-stats';
+  placement = 'top-left' as WidgetPlacement;
+
+  private _counter = 0;
+  private _formatters: Record<string, (stat: Stat) => string>;
+  private _resetOnUpdate: Record<string, boolean>;
+  collapsed: boolean = true;
+  _stats: Stats;
+
+  constructor(props: StatsWidgetProps = {}) {
+    super(props, StatsWidget.defaultProps);
+    this._formatters = {...DEFAULT_FORMATTERS};
+    this.setProps(props);
+    this._resetOnUpdate = {...this.props.resetOnUpdate};
+    this._stats = this.props.stats;
+  }
+
+  setProps(props: Partial<StatsWidgetProps>): void {
+    super.setProps(props);
+    this._stats = this._getStats();
+    if (props.formatters) {
+      for (const name in props.formatters) {
+        const f = props.formatters[name];
+        this._formatters[name] =
+          typeof f === 'string' ? DEFAULT_FORMATTERS[f] || DEFAULT_COUNT_FORMATTER : f;
+      }
+    }
+    if (props.resetOnUpdate) {
+      this._resetOnUpdate = {...props.resetOnUpdate};
+    }
+  }
+
+  onAdd(): void {
+    this._stats = this._getStats();
+    this.updateHTML();
+  }
+
+  onRenderHTML(rootElement: HTMLElement): void {
+    const stats = this._stats;
+    const collapsed = this.collapsed;
+    const title = this.props.title || stats?.id || 'Stats';
+    const items: JSX.Element[] = [];
+
+    if (!collapsed && stats) {
+      stats.forEach(stat => {
+        const lines = this._getLines(stat);
+        if (this._resetOnUpdate && this._resetOnUpdate[stat.name]) {
+          stat.reset();
+        }
+        lines.forEach((line, i) => {
+          items.push(
+            <div key={`${stat.name}-${i}`} style={{whiteSpace: 'pre'}}>
+              {line}
+            </div>
+          );
+        });
+      });
+    }
+
+    render(
+      <div className="deck-widget-stats-container" style={{cursor: 'default'}}>
+        <div
+          className="deck-widget-stats-header"
+          style={{cursor: 'pointer', pointerEvents: 'auto'}}
+          onClick={this._toggleCollapsed}
+        >
+          {collapsed ? RIGHT_ARROW : DOWN_ARROW} {title}
+        </div>
+        {!collapsed && <div className="deck-widget-stats-content deck-widget-common">{items}</div>}
+      </div>,
+      rootElement
+    );
+  }
+
+  onRedraw(): void {
+    const framesPerUpdate = Math.max(1, this.props.framesPerUpdate || 1);
+    if (this._counter++ % framesPerUpdate === 0) {
+      console.log('Redrawing stats widget');
+      this.updateHTML();
+    }
+  }
+
+  protected _getStats(): Stats {
+    switch (this.props.type) {
+      case 'deck':
+        // @ts-expect-error stats is protected
+        return this.deck?.stats;
+      case 'luma':
+        return Array.from(luma.stats.stats.values())[0];
+      case 'device':
+        // @ts-expect-error is protected
+        const device = this.deck?.device;
+        const stats = device?.statsManager.stats.values();
+        return stats ? Array.from(stats)[0] : undefined;
+      case 'custom':
+        return this.props.stats;
+      default:
+        throw new Error(`Unknown stats type: ${this.props.type}`);
+    }
+  }
+
+  protected _toggleCollapsed = (): void => {
+    this.collapsed = !this.collapsed;
+    this.updateHTML();
+  };
+
+  protected _getLines(stat: Stat): string[] {
+    const formatter =
+      this._formatters[stat.name] || this._formatters[stat.type || ''] || DEFAULT_COUNT_FORMATTER;
+    return formatter(stat).split('\n');
+  }
+}