@foxglove/extension 2.27.0 → 2.28.0

package/package.json

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

package/src/experimental.ts

@@ -1,53 +1,6 @@
 /* eslint-disable @typescript-eslint/no-namespace */
 
-import { Immutable } from "./immutable";
-import {
-  ExtensionContext as BaseExtensionContext,
-  RegisterMessageConverterArgs as LegacyRegisterMessageConverterArgs,
-  MessageEvent,
-} from "./stable";
-
-export type MessageSchemaField = "string" | "number" | "bool" | "byte";
-
-/**
- * Describes the structure of a message with field names and their types.
- *
- * @example
- * ```typescript
- * {
- *   // Primitive fields
- *   position: "number",
- *   name: "string",
- *   active: "bool",
- *   singleByte: "byte",
- *
- *   // Arrays of primitive types
- *   coordinates: ["number"],
- *   labels: ["string"],
- *   flags: ["bool"],
- *   rawData: ["byte"],
- *
- *   // Nested objects
- *   metadata: {
- *     timestamp: "number",
- *     source: "string"
- *   },
- *
- *   // Arrays of objects
- *   points: [{
- *     x: "number",
- *     y: "number",
- *     z: "number"
- *   }]
- * }
- * ```
- */
-export type MessageSchemaDescription = {
-  [key: string]:
-    | MessageSchemaField
-    | MessageSchemaDescription
-    | [MessageSchemaField | MessageSchemaDescription];
-};
+import { ExtensionContext as BaseExtensionContext } from "./stable";
 
 /**
  * The experimental namespace contains experimental APIs that are not yet stable and WILL change or
@@ -60,155 +13,9 @@ export type MessageSchemaDescription = {
  * @hidden
  */
 export namespace Experimental {
-  type TopicConverterReturnType = (messageEvent: Immutable<MessageEvent>) => unknown;
-  /**
-   * This type represents the arguments you pass to
-   * {@link ExtensionContext.registerMessageConverter} when you want to register a topic message
-   * converter.
-   *
-   * @category Message converters
-   */
-  export type RegisterMessageConverterArgsTopic = {
-    type: "topic";
-    inputTopics: string[];
-    outputTopic: string;
-    schemaName: string;
-    /**
-     * Describes the structure of the output messages produced by this converter.
-     *
-     * This optional field allows Foxglove to understand the structure of your messages, enabling
-     * features like autocompletion for message path selection.
-     *
-     * The schema can include:
-     * - Primitive types: "string", "number", "bool", "byte"
-     * - Arrays of primitives: ["string"], ["number"], ["bool"], ["byte"]
-     * - Nested objects with their own field definitions
-     * - Arrays of objects (each element having the same structure)
-     *
-     * @example
-     * ```
-     * schemaDescription: {
-     *   // Simple fields
-     *   timestamp: "number",
-     *   label: "string",
-     *   enabled: "bool",
-     *   flags: "byte",
-     *
-     *   // Array of primitives
-     *   values: ["number"],
-     *   names: ["string"],
-     *   options: ["bool"],
-     *   data: ["byte"],
-     *
-     *   // Nested object
-     *   position: {
-     *     x: "number",
-     *     y: "number",
-     *     z: "number"
-     *   },
-     *
-     *   // Array of objects
-     *   landmarks: [{
-     *     id: "string",
-     *     position: {
-     *       x: "number",
-     *       y: "number"
-     *     }
-     *   }]
-     * }
-     * ```
-     */
-    schemaDescription?: MessageSchemaDescription;
-    create: () => TopicConverterReturnType;
-  };
-
-  /**
-   * This type represents the arguments you pass to
-   * {@link ExtensionContext.registerMessageConverter} when you want to register a schema message
-   * converter.
-   *
-   * `schema` converters allow you to leverage Foxglove's built-in visualization panels by
-   * transforming messages to adhere to Foxglove-supported schemas — for example, you can convert
-   * your custom GPS messages to
-   * [`foxglove.LocationFix`](https://docs.foxglove.dev/docs/visualization/message-schemas/location-fix)
-   * messages for visualization in the [Map
-   * panel](https://docs.foxglove.dev/docs/visualization/panels/map).
-   *
-   * See the [Creating a message
-   * converter](https://docs.foxglove.dev/docs/visualization/extensions/guides/create-message-converter)
-   * guide for more details.
-   *
-   * @category Message converters
-   */
-  export type RegisterMessageConverterArgsSchema<Src = unknown> = {
-    type: "schema";
-
-    /** The source message schema name. This is the schema name of the original message. */
-    fromSchemaName: string;
-
-    /**
-     * The converted message schema name. This is the schema name of the message you will output
-     * from the converter.
-     */
-    toSchemaName: string;
-
-    /**
-     * A function which takes the original message and returns the converted message.
-     *
-     * If the function returns `undefined`, the output is ignored, and no message is provided to the
-     * panel. This is useful if you want to selectively output converted messages depending on the
-     * input messages' contents.
-     */
-    converter: (msg: Src, event: Immutable<MessageEvent<Src>>) => unknown;
-  };
-
-  export type RegisterMessageConverterArgs =
-    | LegacyRegisterMessageConverterArgs
-    | RegisterMessageConverterArgsSchema
-    | RegisterMessageConverterArgsTopic;
-
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
   export interface ExtensionContext extends BaseExtensionContext {
-    /**
-     * `registerMessageConverter` registers converters to transform message data within Foxglove.
-     *
-     * You can register two kinds of converters: `schema` and `topic`.
-     *
-     * `schema` converters transform messages of one schema into another. Most often this is used to
-     * turn messages using a custom or proprietary schema into a well-known Foxglove schema for
-     * visualization in one of the built-in panels. `schema` converters allow a built-in panel which
-     * requires well-known messages to natively support visualizing any topic for which there is a
-     * schema converter registered. An example is converting an `acme.Gps` message to
-     * `foxglove.LocationFix` to visualize any topics which publish `acme.Gps` messages in the
-     * built-in map panel.
-     *
-     * See: {@link RegisterMessageConverterArgsSchema}.
-     *
-     * `topic` converters transform messages from one-or-more input topics to a new in-app topic.
-     * Topic converters are more flexible than schema converters but require more logic and
-     * decisions to implement. They can transform existing data into new topics for plotting,
-     * inspecting, and visualizing. Topic converters can combine data from several input topics,
-     * maintain state, and create messages from these multiple topics. They can also do the opposite
-     * - take a single topic and turn it into multiple output topics.
-     *
-     * See: {@link RegisterMessageConverterArgsTopic}.
-     */
-    registerMessageConverter(args: RegisterMessageConverterArgs): void;
-    /**
-     * @deprecated Use `registerMessageConverter` with `type: "schema"` or `type: "topic"` instead.
-     */
-    registerMessageConverter<Src>(args: LegacyRegisterMessageConverterArgs<Src>): void;
-    /**
-     * Register a schema message converter.
-     *
-     * See: {@link RegisterMessageConverterArgsSchema}.
-     */
-    registerMessageConverter<Src>(args: RegisterMessageConverterArgsSchema<Src>): void;
-    /**
-     * Register a topic message converter.
-     *
-     * See: {@link RegisterMessageConverterArgsTopic}.
-     */
-    registerMessageConverter(args: RegisterMessageConverterArgsTopic): void;
+    // no-op until we have experimental APIs
   }
 
   export interface ExtensionModule {

package/src/stable.ts

@@ -879,17 +879,170 @@ export type ExtensionPanelRegistration = {
   initPanel: (context: PanelExtensionContext) => void | (() => void);
 };
 
+export type MessageSchemaField = "string" | "number" | "bool" | "byte";
+
 /**
- * This type represents the arguments you pass to {@link ExtensionContext.registerMessageConverter}.
+ * Describes the structure of a message with field names and their types.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   // Primitive fields
+ *   position: "number",
+ *   name: "string",
+ *   active: "bool",
+ *   singleByte: "byte",
+ *
+ *   // Arrays of primitive types
+ *   coordinates: ["number"],
+ *   labels: ["string"],
+ *   flags: ["bool"],
+ *   rawData: ["byte"],
+ *
+ *   // Nested objects
+ *   metadata: {
+ *     timestamp: "number",
+ *     source: "string"
+ *   },
+ *
+ *   // Arrays of objects
+ *   points: [{
+ *     x: "number",
+ *     y: "number",
+ *     z: "number"
+ *   }]
+ * }
+ * ```
+ */
+export type MessageSchemaDescription = {
+  [key: string]:
+    | MessageSchemaField
+    | MessageSchemaDescription
+    | [MessageSchemaField | MessageSchemaDescription];
+};
+
+/**
+ * This type represents the arguments you pass to
+ * {@link ExtensionContext.registerMessageConverter} when you want to register a topic message
+ * converter.
+ *
+ * @category Message converters
+ */
+export type RegisterMessageConverterArgsTopic = {
+  type: "topic";
+  inputTopics: string[];
+  outputTopic: string;
+  schemaName: string;
+  /**
+   * Describes the structure of the output messages produced by this converter.
+   *
+   * This optional field allows Foxglove to understand the structure of your messages, enabling
+   * features like autocompletion for message path selection.
+   *
+   * The schema can include:
+   * - Primitive types: "string", "number", "bool", "byte"
+   * - Arrays of primitives: ["string"], ["number"], ["bool"], ["byte"]
+   * - Nested objects with their own field definitions
+   * - Arrays of objects (each element having the same structure)
+   *
+   * @example
+   * ```
+   * schemaDescription: {
+   *   // Simple fields
+   *   timestamp: "number",
+   *   label: "string",
+   *   enabled: "bool",
+   *   flags: "byte",
+   *
+   *   // Array of primitives
+   *   values: ["number"],
+   *   names: ["string"],
+   *   options: ["bool"],
+   *   data: ["byte"],
+   *
+   *   // Nested object
+   *   position: {
+   *     x: "number",
+   *     y: "number",
+   *     z: "number"
+   *   },
+   *
+   *   // Array of objects
+   *   landmarks: [{
+   *     id: "string",
+   *     position: {
+   *       x: "number",
+   *       y: "number"
+   *     }
+   *   }]
+   * }
+   * ```
+   */
+  schemaDescription?: MessageSchemaDescription;
+  create: () => TopicConverterReturnType;
+};
+
+type TopicConverterReturnType = (messageEvent: Immutable<MessageEvent>) => unknown;
+
+/**
+ * This type represents the arguments you pass to
+ * {@link ExtensionContext.registerMessageConverter} when you want to register a schema message
+ * converter.
+ *
+ * `schema` converters allow you to leverage Foxglove's built-in visualization panels by
+ * transforming messages to adhere to Foxglove-supported schemas — for example, you can convert
+ * your custom GPS messages to
+ * [`foxglove.LocationFix`](https://docs.foxglove.dev/docs/visualization/message-schemas/location-fix)
+ * messages for visualization in the [Map
+ * panel](https://docs.foxglove.dev/docs/visualization/panels/map).
+ *
+ * See the [Creating a message
+ * converter](https://docs.foxglove.dev/docs/visualization/extensions/guides/create-message-converter)
+ * guide for more details.
  *
  * @category Message converters
  */
-export type RegisterMessageConverterArgs<Src = unknown> = {
+export type RegisterMessageConverterArgsSchema<Src = unknown> = {
+  type: "schema";
+
+  /** The source message schema name. This is the schema name of the original message. */
+  fromSchemaName: string;
+
+  /**
+   * The converted message schema name. This is the schema name of the message you will output
+   * from the converter.
+   */
+  toSchemaName: string;
+
+  /**
+   * A function which takes the original message and returns the converted message.
+   *
+   * If the function returns `undefined`, the output is ignored, and no message is provided to the
+   * panel. This is useful if you want to selectively output converted messages depending on the
+   * input messages' contents.
+   */
+  converter: (msg: Src, event: Immutable<MessageEvent<Src>>) => unknown;
+};
+
+/**
+ * @deprecated Use {@link RegisterMessageConverterArgsSchema} instead.
+ */
+export type LegacyRegisterMessageConverterArgs<Src = unknown> = {
   fromSchemaName: string;
   toSchemaName: string;
   converter: (msg: Src, event: Immutable<MessageEvent<Src>>) => unknown;
 };
 
+/**
+ * This type represents the arguments you pass to {@link ExtensionContext.registerMessageConverter}.
+ *
+ * @category Message converters
+ */
+export type RegisterMessageConverterArgs =
+  | LegacyRegisterMessageConverterArgs
+  | RegisterMessageConverterArgsSchema
+  | RegisterMessageConverterArgsTopic;
+
 /** @category Topic aliases */
 export type BaseTopic = { name: string; schemaName?: string };
 /** @category Topic aliases */
@@ -942,27 +1095,46 @@ export interface ExtensionContext {
   registerPanel(params: ExtensionPanelRegistration): void;
 
   /**
-   * `registerMessageConverter` registers a function to convert messages from one schema to another.
+   * `registerMessageConverter` registers converters to transform message data within Foxglove.
    *
-   * Message converters allow you to leverage Foxglove's built-in visualization panels by
-   * transforming messages to adhere to Foxglove-supported schemas — for example, you can convert
-   * your custom GPS messages to
-   * [`foxglove.LocationFix`](https://docs.foxglove.dev/docs/visualization/message-schemas/location-fix)
-   * messages for visualization in the [Map
-   * panel](https://docs.foxglove.dev/docs/visualization/panels/map).
+   * You can register two kinds of converters: `schema` and `topic`.
    *
-   * Whenever a panel subscribes to a topic with the
-   * [`convertTo`](https://docs.foxglove.dev/docs/visualization/extensions/api/panel#message-converters)
-   * option, the converter function runs on the original message and outputs the converted message,
-   * which it then provides it to the panel. If the function returns `undefined`, the output is
-   * ignored, and no message is provided to the panel. This is useful if you want to selectively
-   * output converted messages depending on the input messages' contents.
+   * `schema` converters transform messages of one schema into another. Most often this is used to
+   * turn messages using a custom or proprietary schema into a well-known Foxglove schema for
+   * visualization in one of the built-in panels. `schema` converters allow a built-in panel which
+   * requires well-known messages to natively support visualizing any topic for which there is a
+   * schema converter registered. An example is converting an `acme.Gps` message to
+   * `foxglove.LocationFix` to visualize any topics which publish `acme.Gps` messages in the
+   * built-in map panel.
    *
-   * See the [Creating a message
-   * converter](https://docs.foxglove.dev/docs/visualization/extensions/guides/create-message-converter)
-   * guide for more details.
+   * See: {@link RegisterMessageConverterArgsSchema}.
+   *
+   * `topic` converters transform messages from one-or-more input topics to a new in-app topic.
+   * Topic converters are more flexible than schema converters but require more logic and
+   * decisions to implement. They can transform existing data into new topics for plotting,
+   * inspecting, and visualizing. Topic converters can combine data from several input topics,
+   * maintain state, and create messages from these multiple topics. They can also do the opposite
+   * - take a single topic and turn it into multiple output topics.
+   *
+   * See: {@link RegisterMessageConverterArgsTopic}.
+   */
+  registerMessageConverter(args: RegisterMessageConverterArgs): void;
+  /**
+   * @deprecated Use `registerMessageConverter` with `type: "schema"` or `type: "topic"` instead.
+   */
+  registerMessageConverter<Src>(args: LegacyRegisterMessageConverterArgs<Src>): void;
+  /**
+   * Register a schema message converter.
+   *
+   * See: {@link RegisterMessageConverterArgsSchema}.
+   */
+  registerMessageConverter<Src>(args: RegisterMessageConverterArgsSchema<Src>): void;
+  /**
+   * Register a topic message converter.
+   *
+   * See: {@link RegisterMessageConverterArgsTopic}.
    */
-  registerMessageConverter<Src>(args: RegisterMessageConverterArgs<Src>): void;
+  registerMessageConverter(args: RegisterMessageConverterArgsTopic): void;
 
   /**
    * `registerTopicAliases` registers a function to compute topic aliases. The provided alias
@@ -1236,7 +1408,7 @@ export type SettingsTreeNodeActionItem = {
   type: "action";
 
   /**
-   * A unique idenfier for the action.
+   * A unique identifier for the action.
    */
   id: string;
 
@@ -1256,6 +1428,11 @@ export type SettingsTreeNodeActionItem = {
    * as an icon only if their icon is specified.
    */
   display?: "menu" | "inline";
+
+  /**
+   * Whether this action is disabled or not. Defaults to false.
+   */
+  disabled?: boolean;
 };
 
 /**