@foxglove/extension 2.32.1 → 2.33.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxglove/extension",
-  "version": "2.32.1",
+  "version": "2.33.1",
   "license": "MIT",
   "author": {
     "name": "Foxglove Technologies",

package/src/experimental.ts

@@ -2,7 +2,12 @@
 import type { Immutable } from "./immutable";
 import type {
   ExtensionContext as BaseExtensionContext,
+  MessageEvent,
   PanelExtensionContext as BasePanelExtensionContext,
+  SettingsTreeAction,
+  SettingsTreeFields,
+  SettingsTreeNode,
+  Topic,
 } from "./stable";
 
 /**
@@ -51,6 +56,13 @@ export namespace Experimental {
      * See: {@link RegisterDataLoaderArgs}
      */
     registerDataLoader(args: RegisterDataLoaderArgs): void;
+
+    /**
+     * Register a panel overlay extension to create 2D HTML overlays for 3D and Image panels
+     *
+     * See: {@link PanelOverlayExtensionArgs}
+     */
+    registerPanelOverlay(args: PanelOverlayExtensionArgs): void;
   }
 
   export interface ExtensionModule {
@@ -118,6 +130,98 @@ export namespace Experimental {
    */
   export type PanelToolbarItem = PanelToolbarButton | PanelToolbarLink | PanelToolbarDivider;
 
+  export type PanelOverlayExtensionBaseConfig = { visible: boolean };
+
+  export type PanelOverlaySubscription<T = unknown> = {
+    /**
+     * This method will only be run against Topics with schemas that match the topic or schema of the overarching subscription.
+     * So if you always want to receive messages from a topic with a given name or schema you can simply return true.
+     * These subscriptions will only be active when the custom layer extension's visibility is true.
+     */
+    shouldSubscribe?: (topic: string, schema: string) => boolean;
+    /** Callback that will be fired for each matching incoming message */
+    handler: (messageEvent: MessageEvent<T>) => void;
+    /** Queue of messages to be handled since last frame. Will be reassigned to new empty array each frame. */
+    queue?: MessageEvent<T>[] | undefined;
+    /** Optional callback to be called on `queue` to filter. Returns new queue. */
+    filterQueue?: (queue: MessageEvent<T>[]) => MessageEvent<T>[];
+  };
+
+  export type AnyPanelOverlaySubscription = Immutable<
+    | {
+        type: "schema";
+        schemaNames: Set<string>;
+        // any is used here to allow storing heterogeneous arrays of subscriptions
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        subscription: PanelOverlaySubscription<any>;
+      }
+    | {
+        type: "topic";
+        topicName: string;
+        // any is used here to allow storing heterogeneous arrays of subscriptions
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        subscription: PanelOverlaySubscription<any>;
+      }
+  >;
+
+  export type ActionHandler = (action: SettingsTreeAction) => void;
+
+  export type SettingsTreeNodeWithActionHandler = SettingsTreeNode & { handler?: ActionHandler };
+
+  export type SettingsPath = ReadonlyArray<string>;
+
+  export type SettingsTreeEntry = { path: SettingsPath; node: SettingsTreeNodeWithActionHandler };
+
+  export interface PanelOverlayExtensionContext<
+    Config extends PanelOverlayExtensionBaseConfig = PanelOverlayExtensionBaseConfig,
+  > {
+    /** Get the current config object for the panel overlay. */
+    getConfig: () => PanelOverlayExtensionBaseConfig & Partial<Config>;
+    /** Update the config object for the panel overlay.
+     * The draft object is meant to be mutated and set to the desired state.
+     */
+    updateConfig: (updateHandler: (draft: Partial<Config>) => void) => void;
+    /** Get all available topics that can be subscribed to. */
+    getTopics: () => readonly Topic[];
+    /** Queue an animation frame. This will call the extension's `startFrame` when the next animation frame is ready.*/
+    queueAnimationFrame: () => void;
+    /** The container element where the panel overlay will be rendered.
+     * The extension is meant to either use this as a react root element, or append elements and update them manually.
+     */
+    overlayContainerElement: HTMLElement;
+  }
+  export interface PanelOverlayExtension {
+    /** The unique identifier for the panel overlay. */
+    readonly id: string;
+    /** The label to display in the settings panel for the panel overlay. */
+    readonly label?: string;
+    getSubscriptions: () => AnyPanelOverlaySubscription[];
+    /** Callback that will be fired when the available topics change.
+     * To get the new state of topics call `getTopics`.
+     */
+    onTopicsChanged: () => void;
+    /** Called when there is a user-driven settings change from the settings panel.  */
+    handleSettingsAction: (action: SettingsTreeAction) => void;
+    /** Used to specify the desired fields in the panel overlay's section of the settings tree */
+    settingsNodeFields: () => SettingsTreeFields;
+    /** Will be called when there is a seek on the playback bar or sometimes when subscriptions change. */
+    onSeek: () => void;
+    /** Will be called every time the panel canvas is re-rendered by an animation frame. */
+    startFrame: () => void;
+    /** Will be called when the 3D Renderer is disposed because of a parameter change or the panel is unmounted. */
+    dispose: () => void;
+  }
+
+  export type PanelOverlayExtensionArgs<
+    Config extends PanelOverlayExtensionBaseConfig = PanelOverlayExtensionBaseConfig,
+  > = {
+    /** The unique identifier for the panel overlay - should match the id of the PanelOverlay */
+    id: string;
+    /** Specifies the default config for the panel overlay. */
+    defaultConfig: Config;
+    init: (context: PanelOverlayExtensionContext) => PanelOverlayExtension;
+  };
+
   export interface PanelExtensionContext extends BasePanelExtensionContext {
     /**
      * Set the items in the panel toolbar.

package/src/stable.ts

@@ -1233,7 +1233,6 @@ export interface ExtensionModule {
 export type SettingsIcon =
   | "Add"
   | "Addchart"
-  | "AutoAwesome"
   | "Background"
   | "Camera"
   | "Cells"
@@ -1535,6 +1534,11 @@ export type SettingsTreeNode = {
    */
   label?: string;
 
+  /**
+   * Optional help text to explain the purpose of the node.
+   */
+  help?: string;
+
   /**
    * True if the node label can be edited by the user.
    */