feat: per host layout for the terminal panel bar

packages/plugin-sdk/CHANGELOG.md

@@ -6,6 +6,7 @@ Plugin API 1.10.0.
 
 ### Added
 
+- `app.registerCompanionLayout` and `useCompanions`, so a plugin can let each host turn the panel bar on or off, move it and choose which panels show and in what order
 - `clientCert` on the sync link, link patch and remote target, and the `client_cert` remote error kind, so a sync plugin can link to a server that needs mutual TLS
 
 ## 1.0.17

packages/plugin-sdk/PLUGIN-GUIDE.md

@@ -496,6 +496,7 @@ your plugin's error boundary and Suspense.
 | `registerRailItem`                                                                 | A sidebar rail button                                             |
 | `registerTab`, `registerPanel`                                                     | A tab type or sidebar panel (id in `contributes.tabs` / `panels`) |
 | `registerCompanion`, `toggleCompanion`                                             | A panel beside any host tab, bound to its host and handle         |
+| `registerCompanionLayout`                                                          | Per host on/off, side, order and hidden panels for a tab type     |
 | `registerDashboardCard`                                                            | A dashboard card (`contributes.dashboardCards`)                   |
 | `registerHostAction`                                                               | A host button, palette entry or default connect                   |
 | `registerHostEditorSection`                                                        | Your own host editor section (host settings get one for free)     |

packages/plugin-sdk/src/frontend.ts

@@ -825,6 +825,26 @@ export interface CompanionDefaults {
   edgeButton?: boolean;
 }
 
+/** A panel a tab type can show beside it, for a picker. */
+export interface CompanionInfo {
+  /** The id registerCompanionLayout's hidden and order lists use. */
+  id: string;
+  titleKey: string;
+  icon?: IconComponent;
+}
+
+/** How a host wants the panel bar beside a tab. */
+export interface CompanionLayout {
+  /** False removes the bar and its panels. */
+  enabled?: boolean;
+  /** Where a panel opens until the user moves it. */
+  side?: "left" | "right" | "bottom";
+  /** Companion ids in bar order. */
+  order?: string[];
+  /** Companion ids left out. */
+  hidden?: string[];
+}
+
 export interface CompanionProps {
   /** The tab it sits beside. */
   tab: PluginTabRecord;
@@ -1118,6 +1138,14 @@ export interface TermixApp extends TermixAppInfo {
     component: ComponentType<CompanionProps>,
     options?: CompanionOptions,
   ) => Disposer;
+  /**
+   * Lets a plugin decide, per host, how the panel bar looks on one tab type.
+   * Read from the host payload, so it must not call hooks.
+   */
+  registerCompanionLayout: (
+    tabType: string,
+    resolve: (host: PluginHostRecord | undefined) => CompanionLayout,
+  ) => Disposer;
   /** Opens a companion on a tab, or closes it when it is showing. */
   toggleCompanion: (tab: PluginTabRecord, id?: string) => void;
   registerHostEditorSection: (
@@ -1347,6 +1375,7 @@ export interface PluginHostBridge {
   hostProtocols: (host: PluginHostRecord) => string[];
   useHostStatus: (hostId: number | undefined) => HostStatusInfo | null;
   useHostActions: () => HostActionContribution[];
+  useCompanions: (tabType: string) => CompanionInfo[];
   useActivityTypes: () => string[];
   activityTarget: (type: string) => ActivityTargetInfo | undefined;
   useExtensions: (pointId: string) => ExtensionContribution[];
@@ -1756,6 +1785,14 @@ export function useHostActions(): HostActionContribution[] {
   return requireHost().useHostActions();
 }
 
+/**
+ * Every panel that can open beside a tab of this type, for a settings screen
+ * that lets the user hide or reorder them. Reactive.
+ */
+export function useCompanions(tabType: string): CompanionInfo[] {
+  return requireHost().useCompanions(tabType);
+}
+
 /**
  * Recent-activity types every registered tab claims (registerTab's
  * activityTypes), core's and plugins'. For a filter that lists what a user

packages/plugin-sdk/src/testing/setup.ts

@@ -139,6 +139,7 @@ const offline = () =>
   }),
   hostProtocols: () => ["ssh"],
   useHostActions: () => [],
+  useCompanions: () => [],
   useActivityTypes: () => [],
   activityTarget: () => undefined,
   useExtensions: () => [],