@foxglove/extension 2.29.1 → 2.31.0

package/README.md

@@ -2,7 +2,7 @@
 
 This package contains type definitions for writing [Foxglove](https://foxglove.dev/) extensions.
 
-See https://docs.foxglove.dev/docs/visualization/extensions/introduction
+See https://docs.foxglove.dev/docs/extensions
 
 ## Stay in touch
 

package/package.json

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

package/src/stable.ts

@@ -360,7 +360,7 @@ export type SubscribeMessageRangeArgs = {
  * extension `panelElement` unmounts.
  *
  * See the [Creating a custom
- * panel](https://docs.foxglove.dev/docs/visualization/extensions/guides/create-custom-panel) guide
+ * panel](https://docs.foxglove.dev/docs/extensions/guides/create-custom-panel) guide
  * for more details.
  *
  * @category Custom panels
@@ -415,7 +415,7 @@ export type PanelExtensionContext = {
   /**
    * Use `context.saveState` to save an arbitrary object as persisted panel state (also known as
    * panel settings) in the current layout. You can view the current panel state using
-   * [Import/export settings](https://docs.foxglove.dev/docs/visualization/panels/introduction#importexport-settings).
+   * [Import/export settings](https://docs.foxglove.dev/docs/visualization/panels#importexport-settings).
    *
    * ```ts
    * context.initialState = undefined; // your panel's initial state
@@ -932,7 +932,21 @@ export type RegisterMessageConverterArgsTopic = {
   type: "topic";
   inputTopics: string[];
   outputTopic: string;
-  schemaName: string;
+
+  /** Name of the schema for messages output by the converter.
+   *
+   * If you output well-known messages like a foxglove CompressedImage then your schema name would
+   * be `foxglove.CompressedImage`.
+   *
+   * If you are creating a new custom schema you can assign any name. Avoid picking an existing name
+   * if your data uses a different schema.
+   *
+   * NOTE: For ROS users, we also support names like `sensor_msgs/msg/CompressedImage`. See the
+   * supported messages documentation for each panel to learn what kinds of schemas it can display.
+   *
+   */
+  outputSchemaName: string;
+
   /**
    * Describes the structure of the output messages produced by this converter.
    *
@@ -978,11 +992,38 @@ export type RegisterMessageConverterArgsTopic = {
    * }
    * ```
    */
+  outputSchemaDescription?: MessageSchemaDescription;
+
+  /** @deprecated use `outputSchemaName` instead */
+  schemaName?: string;
+
+  /** @deprecated use `outputSchemaDescription` instead */
   schemaDescription?: MessageSchemaDescription;
+
+  /**
+   *
+   * The create function initializes the converter. It is called by the app to create the converter
+   * when some panel subscribes to the output topic.
+   *
+   * ```
+   * create: () => {
+   *   return (msgEvent: MessageEvent) => {
+   *     const msg = msgEvent.message as MySignal;
+   *     return { value: Math.abs(msg.acceleration) };
+   *   };
+   * },
+   * ```
+   *
+   * @returns A function that is called with a MessageEvent for every input message. It performs any
+   * computation and returns a new message(s) matching the schema description. The function can
+   * optionally return undefined to skip producing message(s) for the given input.
+   */
   create: () => TopicConverterReturnType;
 };
 
-type TopicConverterReturnType = (messageEvent: Immutable<MessageEvent>) => unknown;
+type TopicConverterReturnType = (
+  messageEvent: Immutable<MessageEvent>,
+) => undefined | Record<string, unknown> | Record<string, unknown>[];
 
 /**
  * This type represents the arguments you pass to
@@ -996,8 +1037,8 @@ type TopicConverterReturnType = (messageEvent: Immutable<MessageEvent>) => unkno
  * 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)
+ * See the [Creating a topic
+ * converter](https://docs.foxglove.dev/docs/extensions/guides/create-topic-converter)
  * guide for more details.
  *
  * @category Message converters
@@ -1089,7 +1130,7 @@ export interface ExtensionContext {
    * optional cleanup function to run when the extension `panelElement` unmounts.
    *
    * See the [Creating a custom
-   * panel](https://docs.foxglove.dev/docs/visualization/extensions/guides/create-custom-panel)
+   * panel](https://docs.foxglove.dev/docs/extensions/guides/create-custom-panel)
    * guide for more details.
    */
   registerPanel(params: ExtensionPanelRegistration): void;
@@ -1284,7 +1325,7 @@ export type SettingsTreeFieldValue =
       validTypes?: string[];
       /** Only include paths from these topics in autocomplete suggestions */
       validTopics?: string[];
-      /** True if the input should allow math modifiers like @abs */
+      /** True if the input should allow math modifiers like "@abs" */
       supportsMathModifiers?: boolean;
     }
   | {