@deck.gl-community/widgets 9.2.5 → 9.3.0-beta.1

package/src/index.ts

@@ -2,17 +2,114 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-export {PanWidget} from './widgets/pan-widget';
-export type {PanWidgetProps} from './widgets/pan-widget';
+export {PanWidget} from './graph-widgets/pan-widget';
+export type {PanWidgetProps} from './graph-widgets/pan-widget';
 
-export {ZoomRangeWidget} from './widgets/zoom-range-widget';
-export type {ZoomRangeWidgetProps} from './widgets/zoom-range-widget';
+export {ZoomRangeWidget} from './graph-widgets/zoom-range-widget';
+export type {ZoomRangeWidgetProps} from './graph-widgets/zoom-range-widget';
 
-export {HtmlOverlayWidget} from './widgets/html-overlay-widget';
-export type {HtmlOverlayWidgetProps} from './widgets/html-overlay-widget';
-export {HtmlOverlayItem} from './widgets/html-overlay-item';
-export type {HtmlOverlayItemProps} from './widgets/html-overlay-item';
-export {HtmlClusterWidget} from './widgets/html-cluster-widget';
-export type {HtmlClusterWidgetProps} from './widgets/html-cluster-widget';
-export {HtmlTooltipWidget} from './widgets/html-tooltip-widget';
-export type {HtmlTooltipWidgetProps} from './widgets/html-tooltip-widget';
+export {HtmlOverlayWidget} from './html-overlay-widgets/html-overlay-widget';
+export type {HtmlOverlayWidgetProps} from './html-overlay-widgets/html-overlay-widget';
+export {HtmlOverlayItem} from './html-overlay-widgets/html-overlay-item';
+export type {HtmlOverlayItemProps} from './html-overlay-widgets/html-overlay-item';
+export {HtmlClusterWidget} from './html-overlay-widgets/html-cluster-widget';
+export type {HtmlClusterWidgetProps} from './html-overlay-widgets/html-cluster-widget';
+export {HtmlTooltipWidget} from './html-overlay-widgets/html-tooltip-widget';
+export type {HtmlTooltipWidgetProps} from './html-overlay-widgets/html-tooltip-widget';
+
+export {HeapMemoryWidget} from './widgets/heap-memory-widget';
+export {
+  SettingsWidget,
+  type SettingsWidgetProps,
+  type SettingsWidgetSchema,
+  type SettingsWidgetSectionDescriptor,
+  type SettingsWidgetSettingDescriptor,
+  type SettingsWidgetState
+} from './widgets/settings-widget';
+export {
+  OmniBoxWidget,
+  type OmniBoxOption,
+  type OmniBoxOptionProvider,
+  type OmniBoxRenderOptionArgs,
+  type OmniBoxWidgetProps
+} from './widgets/omni-box-widget';
+export {ResetViewWidget, type ResetViewWidgetProps} from './widget-panels/reset-view-widget';
+export {
+  TimeMeasureWidget,
+  type TimeMeasureRange,
+  type TimeMeasureSelectionState
+} from './widget-panels/time-measure-widget';
+export {ToastWidget, type ToastWidgetProps} from './widget-panels/toast-widget';
+export {
+  toastManager,
+  type ToastEntry,
+  type ToastKind,
+  type ToastRequest
+} from './widget-panels/toast-manager';
+export {YZoomWidget, type YZoomWidgetProps} from './widget-panels/y-zoom-widget';
+export {
+  AccordeonPanel,
+  AccordeonWidgetContainer,
+  ColumnWidgetContainer,
+  ColumnPanel,
+  CustomPanel,
+  MarkdownPanel,
+  TabbedPanel,
+  TabbedWidgetContainer,
+  WidgetContainerRenderer,
+  asPanelContainer,
+  type AccordeonWidgetContainerProps,
+  type AccordeonPanelProps,
+  type ColumnWidgetContainerProps,
+  type ColumnPanelProps,
+  type CustomPanelProps,
+  type MarkdownPanelProps,
+  type TabbedWidgetContainerProps,
+  type TabbedPanelProps,
+  type WidgetContainer,
+  type WidgetContainerPanelBase,
+  type WidgetPanel,
+  type WidgetPanelContainer,
+  type WidgetPanelContainerProps,
+  type WidgetPanelRecord,
+  type WidgetPanelTheme,
+  type WidgetPanelThemeMode
+} from './widget-panels/widget-containers';
+export {BoxWidget, type BoxWidgetProps} from './widget-panels/box-widget';
+export {
+  FullScreenPanelWidget,
+  type FullScreenPanelWidgetProps
+} from './widget-panels/full-screen-panel-widget';
+export {
+  KeyboardShortcutsWidget,
+  KeyboardShortcutsPanel,
+  type KeyboardShortcutsPanelProps
+} from './widget-panels/keyboard-shortcuts-widget';
+export {ModalWidget, type ModalWidgetProps} from './widget-panels/modal-widget';
+export {SettingsPanel, type SettingsPanelProps} from './widget-panels/settings-panel';
+export {
+  SelectWidgetComponent,
+  type SelectWidgetComponentOption,
+  type SelectWidgetComponentProps
+} from './widget-components/select-widget-component';
+export {IconButton, makeTextIcon} from './widget-components/icon-button';
+export {StatsPanel, type StatsPanelProps} from './widget-panels/stats-panel';
+export {SidebarWidget, type SidebarWidgetProps} from './widget-panels/sidebar-widget';
+export {
+  ToolbarWidget,
+  type ToolbarWidgetActionItem,
+  type ToolbarWidgetBadgeItem,
+  type ToolbarWidgetItem,
+  type ToolbarWidgetProps,
+  type ToolbarWidgetToggleGroupItem,
+  type ToolbarWidgetToggleOption
+} from './widget-panels/toolbar-widget';
+export {TextEditorPanel, type TextEditorPanelProps} from './widget-panels/text-editor-panel';
+
+export {
+  type KeyboardShortcut,
+  isShortcutMatchingKeyEvent,
+  findShortcutMatchingKeyEvent,
+  DEFAULT_SHORTCUTS,
+  formatKey
+} from './keyboard-shortcuts/keyboard-shortcuts';

package/src/keyboard-shortcuts/keyboard-shortcuts-manager.ts

@@ -0,0 +1,58 @@
+import {findShortcutMatchingKeyEvent} from './keyboard-shortcuts';
+
+import type {KeyboardShortcut} from './keyboard-shortcuts';
+import type {EventManager, MjolnirKeyEvent} from 'mjolnir.js';
+
+export class KeyboardShortcutsManager {
+  private shortcuts: KeyboardShortcut[] = [];
+  eventManager: EventManager;
+
+  constructor(eventManager: EventManager, shortcuts: KeyboardShortcut[]) {
+    this.eventManager = eventManager;
+    this.shortcuts = shortcuts;
+  }
+
+  start() {
+    // console.log('Installing keyboard shortcuts:', this.shortcuts);
+    this.eventManager.on('keydown', this._handleKeyDown);
+  }
+
+  stop() {
+    this.eventManager.off('keydown', this._handleKeyDown);
+    // console.log('Uninstalling keyboard shortcuts:', this.shortcuts);
+  }
+
+  private _handleKeyDown = (e: MjolnirKeyEvent) => {
+    // console.log('Mjolnir key event:', e);
+    const shortcut = findShortcutMatchingKeyEvent(e.srcEvent, this.shortcuts);
+    if (shortcut) {
+      shortcut?.onKeyPress?.();
+      // e.preventDefault();
+    }
+    // console.log('Key pressed:', e.srcEvent.key, 'Matching shortcut:', shortcut?.name);
+  };
+}
+
+export class KeyboardShortcutsManagerDocument {
+  private shortcuts: KeyboardShortcut[] = [];
+  private _handleKeyDown = (e: KeyboardEvent) => {
+    const shortcut = findShortcutMatchingKeyEvent(e, this.shortcuts);
+    if (shortcut) {
+      shortcut?.onKeyPress?.();
+      // e.preventDefault();
+    }
+    // console.log('Key pressed:', e.key, 'Matching shortcut:', shortcut?.name);
+  };
+
+  constructor(shortcuts: KeyboardShortcut[]) {
+    this.shortcuts = shortcuts;
+  }
+
+  start() {
+    document.addEventListener('keydown', this._handleKeyDown);
+  }
+
+  stop() {
+    document.removeEventListener('keydown', this._handleKeyDown);
+  }
+}

package/src/keyboard-shortcuts/keyboard-shortcuts.ts

@@ -0,0 +1,113 @@
+export type KeyboardShortcut = {
+  key: string;
+  commandKey?: boolean;
+  shiftKey?: boolean;
+  ctrlKey?: boolean;
+  dragMouse?: boolean;
+  badges?: string[];
+  displayPair?: {
+    id: string;
+    position: 'primary' | 'secondary';
+    description: string;
+  };
+
+  name: string;
+  description: string;
+  onKeyPress?: () => void;
+};
+
+export const DEFAULT_SHORTCUTS: KeyboardShortcut[] = [
+  {
+    key: '/',
+    commandKey: true,
+    name: 'Show Shortcuts',
+    description: 'Show keyboard shortcuts'
+  }
+];
+
+const navigator = typeof window !== 'undefined' ? globalThis.navigator : {platform: ''};
+const isMac = navigator.platform.toUpperCase().indexOf('MAC') >= 0;
+
+export const isShortcutMatchingKeyEvent = (e: KeyboardEvent, shortcut: KeyboardShortcut) => {
+  const isCmd = isMac ? e.metaKey : e.ctrlKey;
+  return (
+    shortcut.key.toLowerCase() === e.key.toLowerCase() &&
+    (shortcut.commandKey ? isCmd : true) &&
+    (shortcut.shiftKey ? e.shiftKey : true) &&
+    (shortcut.ctrlKey ? e.ctrlKey : true)
+  );
+};
+
+export const findShortcutMatchingKeyEvent = (e: KeyboardEvent, shortcuts: KeyboardShortcut[]) => {
+  return shortcuts.find((shortcut) => isShortcutMatchingKeyEvent(e, shortcut));
+};
+
+// Pretty “keycap” glyphs for KeyboardEvent.key (browser KeyEvent)
+export const keyCharacter: Record<string, string> = {
+  // Arrows
+  ArrowLeft: '←',
+  ArrowRight: '→',
+  ArrowUp: '↑',
+  ArrowDown: '↓',
+
+  // Navigation
+  Home: '⤒',
+  End: '⤓',
+  PageUp: '⇞',
+  PageDown: '⇟',
+
+  // Editing
+  Backspace: '⌫',
+  Delete: '⌦',
+  Insert: 'Ins',
+
+  // Whitespace / confirm / escape
+  Enter: '⏎',
+  Escape: '⎋',
+  Tab: '⇥',
+  ' ': '␠', // KeyboardEvent.key for Space is literally " "
+  Spacebar: '␠', // legacy (some older browsers)
+
+  // Modifiers
+  Shift: 'Shift', // '⇧',
+  Control: '⌃',
+  Alt: '⌥',
+  Meta: '⌘', // Windows key on Win; Command on macOS
+  CapsLock: '⇪',
+
+  // System / toggles
+  ContextMenu: '≣',
+  PrintScreen: '⎙',
+  ScrollLock: '⇳',
+  Pause: '⏸',
+  NumLock: '⇭',
+
+  // Media keys (common)
+  MediaPlayPause: '⏯',
+  MediaStop: '⏹',
+  MediaTrackNext: '⏭',
+  MediaTrackPrevious: '⏮',
+  AudioVolumeMute: '🔇',
+  AudioVolumeDown: '🔉',
+  AudioVolumeUp: '🔊'
+};
+
+// Optional: normalize a KeyboardEvent into a human-friendly label
+export function formatKey(key: string): string {
+  // Prefer mapping for special keys, otherwise use the raw key (letters, digits, punctuation).
+  // Make single characters uppercase for nicer display.
+  const mapped = keyCharacter[key];
+  if (mapped) return mapped;
+
+  // Function keys: "F1"..."F24"
+  if (/^F\d{1,2}$/.test(key)) return key;
+
+  // Numpad keys often come as "Numpad1", etc.
+  if (key.startsWith('Numpad')) return key.replace('Numpad', 'Num ');
+
+  // For plain characters: show as-is, but uppercase letters.
+  if (key.length === 1) return key.toUpperCase();
+
+  // Fallback for less common named keys
+  return key.toUpperCase();
+}

package/src/keyboard-shortcuts/keyboard-shortcuts.ts.disabled

@@ -0,0 +1,107 @@
+export type KeyboardShortcut = {
+  key: string;
+  commandKey?: boolean;
+  shiftKey?: boolean;
+  ctrlKey?: boolean;
+  dragMouse?: boolean;
+
+  name: string;
+  description: string;
+  onKeyPress?: () => void;
+};
+
+export const DEFAULT_SHORTCUTS: KeyboardShortcut[] = [
+  {
+    key: '/',
+    commandKey: true,
+    name: 'Show Shortcuts',
+    description: 'Show keyboard shortcuts',
+  },
+];
+
+const navigator = typeof window !== 'undefined' ? globalThis.navigator : { platform: '' };
+const isMac = navigator.platform.toUpperCase().indexOf('MAC') >= 0;
+
+export const isShortcutMatchingKeyEvent = (e: KeyboardEvent, shortcut: KeyboardShortcut) => {
+  const isCmd = isMac ? e.metaKey : e.ctrlKey;
+  return (
+    shortcut.key.toLowerCase() === e.key.toLowerCase() &&
+    (shortcut.commandKey ? isCmd : true) &&
+    (shortcut.shiftKey ? e.shiftKey : true) &&
+    (shortcut.ctrlKey ? e.ctrlKey : true)
+  );
+};
+
+export const findShortcutMatchingKeyEvent = (e: KeyboardEvent, shortcuts: KeyboardShortcut[]) => {
+  return shortcuts.find((shortcut) => isShortcutMatchingKeyEvent(e, shortcut));
+};
+
+// Pretty “keycap” glyphs for KeyboardEvent.key (browser KeyEvent)
+export const keyCharacter: Record<string, string> = {
+  // Arrows
+  'ArrowLeft': '←',
+  'ArrowRight': '→',
+  'ArrowUp': '↑',
+  'ArrowDown': '↓',
+
+  // Navigation
+  'Home': '⤒',
+  'End': '⤓',
+  'PageUp': '⇞',
+  'PageDown': '⇟',
+
+  // Editing
+  'Backspace': '⌫',
+  'Delete': '⌦',
+  'Insert': 'Ins',
+
+  // Whitespace / confirm / escape
+  'Enter': '⏎',
+  'Escape': '⎋',
+  'Tab': '⇥',
+  ' ': '␠', // KeyboardEvent.key for Space is literally " "
+  'Spacebar': '␠', // legacy (some older browsers)
+
+  // Modifiers
+  'Shift': '⇧',
+  'Control': '⌃',
+  'Alt': '⌥',
+  'Meta': '⌘', // Windows key on Win; Command on macOS
+  'CapsLock': '⇪',
+
+  // System / toggles
+  'ContextMenu': '≣',
+  'PrintScreen': '⎙',
+  'ScrollLock': '⇳',
+  'Pause': '⏸',
+  'NumLock': '⇭',
+
+  // Media keys (common)
+  'MediaPlayPause': '⏯',
+  'MediaStop': '⏹',
+  'MediaTrackNext': '⏭',
+  'MediaTrackPrevious': '⏮',
+  'AudioVolumeMute': '🔇',
+  'AudioVolumeDown': '🔉',
+  'AudioVolumeUp': '🔊',
+};
+
+// Optional: normalize a KeyboardEvent into a human-friendly label
+export function formatKey(key: string): string {
+  // Prefer mapping for special keys, otherwise use the raw key (letters, digits, punctuation).
+  // Make single characters uppercase for nicer display.
+  const mapped = keyCharacter[key];
+  if (mapped) return mapped;
+
+  // Function keys: "F1"..."F24"
+  if (/^F\d{1,2}$/.test(key)) return key;
+
+  // Numpad keys often come as "Numpad1", etc.
+  if (key.startsWith('Numpad')) return key.replace('Numpad', 'Num ');
+
+  // For plain characters: show as-is, but uppercase letters.
+  if (key.length === 1) return key.toUpperCase();
+
+  // Fallback for less common named keys
+  return key.toUpperCase();
+}

package/src/lib/settings/settings.ts

@@ -0,0 +1,203 @@
+import type {
+  SettingsWidgetOption,
+  SettingsWidgetSchema,
+  SettingsWidgetSectionDescriptor,
+  SettingsWidgetSettingDescriptor,
+  SettingsWidgetState,
+  SettingsWidgetValue
+} from '../../widgets/settings-widget';
+
+export type SettingValue = SettingsWidgetValue;
+export type SettingDescriptor = SettingsWidgetSettingDescriptor;
+export type SettingsSectionDescriptor = SettingsWidgetSectionDescriptor;
+export type SettingsSchema = SettingsWidgetSchema;
+export type SettingsState = SettingsWidgetState;
+
+export function clamp(value: number, min?: number, max?: number): number {
+  let clamped = value;
+  if (Number.isFinite(min)) {
+    clamped = Math.max(min, clamped);
+  }
+  if (Number.isFinite(max)) {
+    clamped = Math.min(max, clamped);
+  }
+  return clamped;
+}
+
+export function setValueAtPath(
+  settings: SettingsState,
+  path: string,
+  value: SettingValue
+): SettingsState {
+  const segments = parsePath(path);
+  if (!segments.length) {
+    return settings;
+  }
+
+  const nextSettings: SettingsState = {...settings};
+  let writeCursor: Record<string, unknown> = nextSettings;
+  let readCursor: Record<string, unknown> = settings;
+
+  segments.forEach((segment, index) => {
+    const isLeaf = index === segments.length - 1;
+
+    if (isLeaf) {
+      writeCursor[segment] = value;
+      return;
+    }
+
+    const existingChild = readCursor[segment];
+    const nextChild = isRecord(existingChild) ? {...existingChild} : {};
+    writeCursor[segment] = nextChild;
+
+    writeCursor = nextChild;
+    readCursor = isRecord(existingChild) ? existingChild : {};
+  });
+
+  return nextSettings;
+}
+
+export function getSectionKey(section: SettingsSectionDescriptor, index: number): string {
+  return section.id ?? section.name ?? `section-${index}`;
+}
+
+export function buildInitialCollapsedState(
+  sections: SettingsSectionDescriptor[]
+): Record<string, boolean> {
+  return sections.reduce<Record<string, boolean>>((result, section, index) => {
+    result[getSectionKey(section, index)] = getInitialCollapsedState(section);
+    return result;
+  }, {});
+}
+
+export function normalizeOption(option: SettingsWidgetOption): {
+  label: string;
+  value: SettingValue;
+} {
+  if (isRecord(option) && 'label' in option && 'value' in option) {
+    return {
+      label: String(option.label),
+      value: option.value
+    };
+  }
+
+  return {
+    label: String(option),
+    value: option
+  };
+}
+
+// eslint-disable-next-line complexity
+export function resolveSettingValue(
+  setting: SettingDescriptor,
+  settings: SettingsState
+): SettingValue {
+  const currentValue = getValueAtPath(settings, setting.name);
+
+  if (setting.type === 'boolean') {
+    return typeof currentValue === 'boolean' ? currentValue : (getDefaultValue(setting) as boolean);
+  }
+
+  if (setting.type === 'number') {
+    const numericValue =
+      typeof currentValue === 'number'
+        ? currentValue
+        : Number.isFinite(Number(currentValue))
+          ? Number(currentValue)
+          : (getDefaultValue(setting) as number);
+    return clamp(numericValue, setting.min, setting.max);
+  }
+
+  if (setting.type === 'select') {
+    const normalizedOptions = (setting.options ?? []).map(normalizeOption);
+    const defaultValue = getDefaultValue(setting);
+    const candidateValue =
+      typeof currentValue === 'string' ||
+      typeof currentValue === 'number' ||
+      typeof currentValue === 'boolean'
+        ? currentValue
+        : defaultValue;
+
+    if (!normalizedOptions.length) {
+      return String(candidateValue);
+    }
+
+    const match = normalizedOptions.find((option) => option.value === candidateValue);
+    return match ? match.value : normalizedOptions[0].value;
+  }
+
+  if (typeof currentValue === 'string') {
+    return currentValue;
+  }
+
+  const defaultValue = getDefaultValue(setting);
+  return typeof defaultValue === 'string' ? defaultValue : String(defaultValue);
+}
+
+export function mergeCollapsedState(
+  previous: Record<string, boolean>,
+  sections: SettingsSectionDescriptor[]
+): Record<string, boolean> {
+  const nextState: Record<string, boolean> = {};
+
+  sections.forEach((section, index) => {
+    const key = getSectionKey(section, index);
+    nextState[key] = previous[key] ?? getInitialCollapsedState(section);
+  });
+
+  return nextState;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function parsePath(path: string): string[] {
+  return path
+    .split('.')
+    .map((segment) => segment.trim())
+    .filter(Boolean);
+}
+
+function getValueAtPath(settings: SettingsState, path: string): unknown {
+  const segments = parsePath(path);
+  if (!segments.length) {
+    return undefined;
+  }
+
+  let current: unknown = settings;
+  for (const segment of segments) {
+    if (!isRecord(current)) {
+      return undefined;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+
+function getInitialCollapsedState(section: SettingsSectionDescriptor): boolean {
+  return section.initiallyCollapsed ?? true;
+}
+
+function getDefaultValue(setting: SettingDescriptor): SettingValue {
+  if (setting.defaultValue !== undefined) {
+    return setting.defaultValue;
+  }
+
+  if (setting.type === 'boolean') {
+    return false;
+  }
+
+  if (setting.type === 'number') {
+    return Number.isFinite(setting.min) ? setting.min : 0;
+  }
+
+  if (setting.type === 'select') {
+    if (setting.options?.length) {
+      return normalizeOption(setting.options[0]).value;
+    }
+    return '';
+  }
+
+  return '';
+}

package/src/ready-to-upstream-widgets/reset-view-widget.tsx

@@ -0,0 +1,57 @@
+/** @jsxImportSource preact */
+import {Widget} from '@deck.gl/core';
+import {render} from 'preact';
+
+import type {WidgetPlacement, WidgetProps} from '@deck.gl/core';
+
+export type ResetViewWidgetProps = WidgetProps & {
+  /** Widget positioning within the view. Default 'top-left'. */
+  placement?: WidgetPlacement;
+  /** Tooltip message */
+  label?: string;
+  /** Callback invoked when the widget button is clicked */
+  onResetView?: () => void;
+};
+
+/** @todo We can likely just add the onResetView callback to the official ResetViewWidget in deck.g; */
+export class ResetViewWidget extends Widget<ResetViewWidgetProps> {
+  static defaultProps: Required<ResetViewWidgetProps> = {
+    ...Widget.defaultProps,
+    id: 'reset-view',
+    placement: 'top-left',
+    label: 'Resize to fit',
+    onResetView: undefined!
+  };
+
+  className = 'deck-widget-reset-view';
+  placement: WidgetPlacement = 'top-left';
+
+  constructor(props: ResetViewWidgetProps = {}) {
+    super(props);
+    this.setProps(this.props);
+  }
+
+  setProps(props: Partial<ResetViewWidgetProps>): void {
+    this.placement = props.placement ?? this.placement;
+    super.setProps(props);
+  }
+
+  onRenderHTML(rootElement: HTMLElement): void {
+    const label = this.props.label ?? 'Resize to fit';
+
+    render(
+      <div className="deck-widget-button">
+        <button
+          className="deck-widget-icon-button deck-widget-reset-focus"
+          type="button"
+          title={label}
+          aria-label={label}
+          onClick={() => this.props.onResetView?.()}
+        >
+          <div className="deck-widget-icon" />
+        </button>
+      </div>,
+      rootElement
+    );
+  }
+}