Skip to main content

Using Managers

Keep application behavior in managers and pass the same descriptors into panels when you want the UI to explain or edit that behavior. This keeps keyboard help, settings controls, and deep-link documentation synchronized with the definitions the app actually uses.

This is the automatic documentation path for descriptor-backed panels: define the app behavior once, then render the panel from that same definition instead of maintaining a second help table by hand.

Manager Pairings​

ManagerApp responsibilityPanel or component using the same source
KeyboardShortcutsManager or KeyboardShortcutsManagerDocumentDispatch KeyboardShortcut[] entriesKeyboardShortcutsPanel renders the same shortcuts as help
SettingsManagerTrack settings snapshots, changes, and persistenceSettingsPanel renders the same SettingsSchema as controls
URLManagerParse and serialize URLParameter[] deep linksURLParametersPanel renders the same URL descriptors as docs
CommandManagerRegister and execute commandsRoute shortcut callbacks into commands; KeyboardShortcutsPanel documents those shortcuts
toastManagerQueue and dismiss notificationsToastComponent renders current toast state
PanelManagerMount PanelComponent[] without deck.glHosts panels and components; it is not a descriptor docs source

Keyboard Shortcuts Become Help​

Define shortcuts once, install them through a manager, and pass the same array to KeyboardShortcutsPanel.

import {
  KeyboardShortcutsManagerDocument,
  KeyboardShortcutsPanel,
  type KeyboardShortcut
} from '@deck.gl-community/panels';

const keyboardShortcuts: KeyboardShortcut[] = [
  {
    key: '/',
    commandKey: true,
    name: 'Show help',
    description: 'Open help.',
    preventDefault: true,
    onKeyPress: () => setHelpOpen(true)
  }
];

const shortcutManager = new KeyboardShortcutsManagerDocument(keyboardShortcuts);
shortcutManager.start();

const helpPanel = new KeyboardShortcutsPanel({keyboardShortcuts});

// Call shortcutManager.stop() when the app removes these shortcuts.

The manager uses onKeyPress; the panel uses the display metadata. Do not maintain a second hand-written shortcut list for help UI.

Settings Schema Becomes Controls​

Register settings descriptors with SettingsManager, then give the same schema and current values to SettingsPanel.

import {
  SettingsManager,
  SettingsPanel,
  getChangedSetting,
  getSettingDefinitions
} from '@deck.gl-community/panels';

const settingsManager = new SettingsManager();
settingsManager.setSettingDefinitions(getSettingDefinitions(settingsSchema));
settingsManager.setLocalStoragePersistence({storageKey: 'app-settings'});

let settings = settingsManager.getSettingsWithLocalStorage(defaultSettings);
settingsManager.setCurrentSettings(settings);

const unsubscribe = settingsManager.setOnSettingsChange((nextSettings, changedSettings) => {
  settings = nextSettings;
  const densityChange = getChangedSetting(changedSettings, 'layout.density');
  if (densityChange) {
    applyDensity(densityChange.nextValue);
  }
  renderPanels();
});

function createSettingsPanel() {
  return new SettingsPanel({
    schema: settingsSchema,
    settings,
    onSettingsChange: nextSettings => settingsManager.setSettings(nextSettings)
  });
}

// Call unsubscribe() when the app removes this settings surface.

getSettingDefinitions(schema) replaces the hand-written schema indexing map. getChangedSetting(changedSettings, name) keeps app reactions focused on one setting instead of repeatedly scanning the emitted change list.

URL parameter descriptors define both serialization behavior and the help panel copy shown to users.

import {
  URLManager,
  URLParametersPanel,
  type URLParameter,
  type URLParameterValue
} from '@deck.gl-community/panels';

type AppState = {
  mode: string;
};

const urlParameters: URLParameter<AppState>[] = [
  {
    name: 'mode',
    description: 'Active view mode.',
    serialize: state => state.mode,
    deserialize: (value: URLParameterValue, state) => {
      if (typeof value === 'string') {
        state.mode = value;
      }
    }
  }
];

const appState: AppState = {mode: 'overview'};
const urlManager = new URLManager(urlParameters);
urlManager.parseIntoState(appState, window.location.search);

const urlParametersPanel = new URLParametersPanel({urlParameters});

The app should update the browser URL through URLManager when state changes; the panel remains documentation for the same canonical and legacy parameter descriptors.

Commands And Toasts​

CommandManager stores executable command metadata, but this package does not currently ship a command leaf panel. When a command has a keyboard shortcut, make the shortcut callback execute the command and let KeyboardShortcutsPanel document the shortcut.

import {commandManager, type KeyboardShortcut} from '@deck.gl-community/panels';

const unregisterReset = commandManager.registerCommand({
  id: 'view.reset',
  label: 'Reset view',
  description: 'Reset the current viewport.',
  do: () => resetView()
});

const commandShortcuts: KeyboardShortcut[] = [
  {
    key: 'r',
    name: 'Reset view',
    description: 'Reset the current viewport.',
    onKeyPress: () => commandManager.executeCommand('view.reset')
  }
];

// Call unregisterReset() when the command leaves the app.

toastManager is similar app-owned state, but its renderer is ToastComponent, not a leaf panel. Mount one toast component once, then let application code call toastManager.toast(...) from anywhere.