@foxglove/extension 2.52.0 → 2.53.0

package/package.json

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

package/src/experimental.ts

@@ -5,6 +5,8 @@ import type {
   MessageEvent as BaseMessageEvent,
   PanelExtensionContext as BasePanelExtensionContext,
   RenderState as BaseRenderState,
+  Subscription as BaseSubscription,
+  Time,
 } from "./stable";
 
 /**
@@ -20,20 +22,35 @@ import type {
 export namespace Experimental {
   export type DataSourceId = string & { __brand: "DataSourceId" };
 
+  /**
+   * Requested start position for a source on the compare timeline.
+   * Manual values are in compare-time seconds and must be non-negative.
+   */
+  export type RequestedDataSourceTimeOffset = { mode: "auto" } | { mode: "manual"; offset: Time };
+
   export type DataSourceInfo = {
     /** ID of the data source (e.g. "A", "B", "C", ...) used to identify the data source. */
     id: DataSourceId;
     /** The name of the data source e.g. the name of the file or URL. */
     name: string;
+    /** User-requested compare-time start configuration. */
+    requestedTimeOffset: RequestedDataSourceTimeOffset;
+    /** Effective time offset applied to source timestamps. */
+    timeOffset: Time;
   };
 
   export type DataSourceMap = ReadonlyMap<DataSourceId, Immutable<DataSourceInfo>>;
 
-  export type MessageEvent = BaseMessageEvent & {
+  export type MessageEvent<T = unknown> = BaseMessageEvent<T> & {
     /** The data source that the message stems from. */
     dataSourceId?: DataSourceId;
   };
 
+  export type Subscription = BaseSubscription & {
+    /** The data source that the subscription stems from. */
+    dataSourceId?: DataSourceId;
+  };
+
   /**
    * This type represents the arguments you pass to {@link ExtensionContext.registerDataLoader}
    * when you want to register a data loader.
@@ -287,11 +304,57 @@ export namespace Experimental {
    */
   export type PanelToolbarItem = PanelToolbarButton | PanelToolbarLink | PanelToolbarDivider;
 
+  /** A metadata record from an MCAP recording. @category Custom panels */
+  export type MetadataRecord = {
+    name: string;
+    metadata: Record<string, string>;
+    /**
+     * Which source this came from in multiplexed playback; `undefined` for single-source.
+     * In merge mode all records share the same `dataSourceId` (the default source's id) —
+     * use `dataSources` to detect compare mode.
+     */
+    dataSourceId?: DataSourceId;
+  };
+
+  /**
+   * Information about an attachment in an MCAP recording — name, size, and timing metadata,
+   * but not the bytes. Use `context.fetchAttachment(id)` to load the bytes on demand.
+   * @category Custom panels
+   */
+  export type AttachmentInfo = {
+    /** Session-scoped id; stable for the playback session but not persistent or globally unique. */
+    id: string;
+    name: string;
+    mediaType: string;
+    logTime: Time;
+    createTime: Time;
+    sizeBytes: number;
+    /**
+     * Which source this came from in multiplexed playback; `undefined` for single-source.
+     * In merge mode all attachments share the same `dataSourceId` (the default source's id),
+     * distinct from the attachment's own `id` above — use `dataSources` to detect compare mode.
+     */
+    dataSourceId?: DataSourceId;
+  };
+
   export type RenderState = BaseRenderState & {
     /**
      * Map of available individual data sources, keyed by their ID.
      */
     dataSources?: DataSourceMap;
+
+    /**
+     * MCAP metadata records from all active sources. In compare mode use `dataSourceId`
+     * to distinguish per-source records.
+     */
+    metadata?: MetadataRecord[];
+
+    /**
+     * MCAP attachment references from all active sources (name/size/timing only, no bytes).
+     * In compare mode use `dataSourceId` to distinguish per-source entries.
+     * Call `context.fetchAttachment(id)` to load bytes.
+     */
+    attachments?: AttachmentInfo[];
   };
 
   export interface PanelExtensionContext extends BasePanelExtensionContext {
@@ -300,21 +363,103 @@ export namespace Experimental {
      * this field changes.
      *
      * Use `context.watch` to indicate which fields in {@link RenderState} (e.g. `currentFrame`,
-     * `currentTime`, `previewTime`, `parameters`, `topics`) should trigger panel re-renders when
-     * their contained values change.
+     * `currentTime`, `previewTime`, `parameters`, `topics`, `metadata`, `attachments`) should
+     * trigger panel re-renders when their contained values change.
      *
      * ```ts
      * context.watch("topics");
      * context.watch("currentFrame");
      * context.watch("parameters");
      * context.watch("currentTime");
+     * context.watch("metadata");
+     * context.watch("attachments");
      * ```
      */
     watch(field: keyof RenderState): void;
 
+    /**
+     * Process render events for the panel. Each render event receives a render state and a done
+     * callback. This override surfaces the experimental {@link RenderState} fields
+     * (`dataSources`, `metadata`, `attachments`) so panels can read them after calling `watch`.
+     */
+    onRender?: (renderState: Immutable<RenderState>, done: () => void) => void;
+
+    /**
+     * Use `context.subscribe` to indicate the topics your panel wants to receive messages for. The
+     * messages are provided during render in {@link RenderState.currentFrame}.
+     *
+     * @remarks
+     *
+     * This method will update the current subscriptions to the new list of Subscriptions and
+     * unsubscribe from any previously subscribed topics no longer in the Subscription list. Passing
+     * an empty array will unsubscribe from all topics.
+     *
+     * ```ts
+     * context.subscribe([{ topic: "/some/topic" }, { topic: "/another/topic" }]);
+     * ```
+     *
+     * `context.subscribe([])` will unsubscribe from all topics, and is equivalent to
+     * `unsubscribeAll`.
+     *
+     * #### Range loading
+     *
+     * Most panels display data from the current frame; examples of built-in panels that display the
+     * current frame are 3D, Image, and Raw Message, however some panels can display data for multiple
+     * messages or even the entire dataset duration (Plot, Map, State Transitions).
+     *
+     * Subscriptions will provide only the messages for the current frame. If your panel would like to
+     * process all the available messages on a topic, use
+     * {@link @PanelExtensionContext.subscribeMessageRange | subscribeMessageRange} instead.
+     *
+     * > NOTE: Message range loading is done on a best-effort basis. If your range-loaded messages
+     * > exceed available memory limits for the browser or desktop app, then the data may not
+     * > represent the full dataset range. Range loading results in more data transfer and memory use
+     * > and is recommended only for panels which require access to the entire dataset.
+     *
+     * #### Message converters
+     *
+     * Message converters can convert messages from one schema to another – for example, a user might
+     * convert custom GPS message into
+     * [`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). Users may have one or more
+     * message converters registered.
+     *
+     * If your panel expects messages with specific schema names, you can leverage registered message
+     * converters to convert from one schema to another.
+     *
+     * Specify the `convertTo` option to enable message conversion on a topic. When conversion is
+     * enabled for a subscription, the {@link MessageEvent}s will contain `message` entries with the
+     * converted message rather than the original message on the topic. The original message is
+     * available in the `originalMessageEvent` field in the message event.
+     *
+     * ```ts
+     * context.subscribe([{ topic: "/some/topic", convertTo: "foxglove.LocationFix" }]);
+     * ```
+     *
+     * The {@link Topic.convertibleTo | convertibleTo} field within {@link RenderState.topics} will
+     * contain the names of schemas you can convert this topic into.
+     */
+    subscribe(subscriptions: Subscription[]): void;
+
+    /**
+     * @deprecated Use `subscribe` with an array of Subscription objects instead.
+     */
+    subscribe(topics: string[]): void;
+
     /**
      * Set the items in the panel toolbar.
      */
     setPanelToolbarItems: (items: Immutable<PanelToolbarItem[]>) => void;
+
+    /**
+     * Load raw bytes for an attachment by `id` (from `RenderState.attachments`). `undefined` when
+     * no attachments are available on the current recording — feature-detect with a truthy check.
+     *
+     * Concurrent calls for the same `id` are deduplicated to a single in-flight request, but
+     * resolved bytes are not cached: a subsequent call after the previous one settles will
+     * re-fetch. Panels that want to keep bytes across renders should memoize the result.
+     */
+    fetchAttachment?: (id: string) => Promise<Uint8Array>;
   }
 }

package/src/stable.ts

@@ -770,6 +770,12 @@ export type PanelExtensionContext = {
    *       case "perform-node-action":
    *         // Handle user-defined actions for nodes in the settings tree
    *         break;
+   *       case "reorder-children":
+   *         if (action.payload.path[0] === "rules") {
+   *           // Move the child identified by action.payload.fromKey before or after
+   *           // action.payload.toKey within the parent node at action.payload.path.
+   *         }
+   *         break;
    *       case "update":
    *         if (action.payload.path[0] === "general" && action.payload.path[1] === "title") {
    *           // Read action.payload.value for the new panel title value
@@ -787,14 +793,20 @@ export type PanelExtensionContext = {
    *
    * #### `SettingsTreeAction`
    *
-   * A {@link SettingsTreeAction} describes how the settings UI should update when a user interacts
-   * with its fields.
+   * A {@link SettingsTreeAction} is a discriminated union describing how the settings UI should
+   * update when a user interacts with it.
    *
-   * Each `SettingsTreeAction` has a `payload` with a `path` to the settings field to update (e.g.
-   * `["general", "title"]`).
+   * All actions include a `payload.path` that identifies the target node or field.
    *
-   * The `update` action corresponds to a user setting a new value for a field (e.g. "My new
-   * title").
+   * - `update` corresponds to a user setting a new field value. Its path points to the field, for
+   *   example `["general", "title"]`.
+   * - `perform-node-action` corresponds to a user invoking a custom node action from `actions`.
+   * - `reorder-children` corresponds to a user reordering the children of a node whose
+   *   `childrenReorderable` property is enabled. Its path points to the parent node, and the payload
+   *   identifies the moved child and destination child by key.
+   *
+   * This union is extended additively over time. To stay forward-compatible, action handlers should
+   * ignore unknown `action` values at runtime instead of throwing from a `default` branch.
    *
    * #### Special node properties
    *
@@ -807,6 +819,10 @@ export type PanelExtensionContext = {
    * editor will provide a button to toggle the visibility of the node and you will receive an
    * `update` action with `visibility` as the final element in the path.
    *
+   * If you set `childrenReorderable` on a node with at least two children, the settings editor lets
+   * users drag and drop that node's children and dispatches `reorder-children` actions when the
+   * user changes their order.
+   *
    * For an example of how to use these special properties, check out the [panel settings example
    * extension](https://github.com/foxglove/create-foxglove-extension/tree/main/examples/panel-settings).
    *
@@ -1635,6 +1651,12 @@ export type SettingsTreeNode = {
    */
   renamable?: boolean;
 
+  /**
+   * Set to `false` on a child of a `childrenReorderable` node to keep this node rendered in place
+   * without drag-and-drop controls or default "Move up" / "Move down" action menu items.
+   */
+  reorderable?: boolean;
+
   /**
    * Optional sort order to override natural object ordering. All nodes
    * with a sort order will be rendered before nodes all with no sort order.
@@ -1646,6 +1668,23 @@ export type SettingsTreeNode = {
    */
   order?: number | string;
 
+  /**
+   * When set to `true`, the renderer treats this node's reorderable children as a
+   * user-reorderable list with drag-and-drop controls and default "Move up" / "Move down" action
+   * menu items when at least two reorderable children are present. Both reorder methods dispatch
+   * "reorder-children" actions whose `path` is the path of this parent node.
+   *
+   * When a visibility filter or tree-wide text filter hides any of this node's children,
+   * drag-and-drop affordances are suppressed until the filter is cleared so that the user is never
+   * dragging against a subset of the list. The action menu items remain available because they
+   * resolve against sibling keys in the complete list.
+   *
+   * When this option is enabled, child render order is driven by the order of entries in
+   * `children`. Explicit `order` values on children are ignored and should not be used for
+   * reorderable children.
+   */
+  childrenReorderable?: boolean;
+
   /**
    * An optional visibility status. If this is not undefined, the node
    * editor will display a visibility toggle button and send update actions
@@ -1684,6 +1723,25 @@ export type SettingsTreeAction =
         "input" | "value"
       >;
     }
+  | {
+      action: "reorder-children";
+      payload: {
+        /** Path to the parent node whose children are being reordered. */
+        path: readonly string[];
+        /**
+         * Key of the child being moved. If this key no longer exists under `path` (for example
+         * because the list changed since the drag started), handlers should ignore the action.
+         */
+        fromKey: string;
+        /**
+         * Key of the child currently occupying the destination slot. If this key no longer
+         * exists under `path`, handlers should ignore the action.
+         */
+        toKey: string;
+        /** Whether the moved child should land before or after `toKey`. */
+        position: "before" | "after";
+      };
+    }
   | {
       action: "perform-node-action";
       payload: { id: string; path: readonly string[] };