@termix-ssh/plugin-sdk 1.0.18 → 1.0.20

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.0.20
+
+Plugin API 1.12.0.
+
+### Added
+
+- `columns` and `onColumns` on `ViewToggle` show a cards per row picker: Auto fits as many as the pane has room for, or pick 1 to 6
+- `size` and `minCardWidth` on `DataView`, so a card grid follows that pick, and the `GridSize` type
+- `usePluginPanelView` also keeps `columns`, the cards per row pick, with `setColumns`
+
+## 1.0.19
+
+Plugin API 1.11.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
+
 ## 1.0.18
 
 Plugin API 1.10.0.

package/PLUGIN-GUIDE.md

@@ -1,6 +1,6 @@
 # Termix plugin guide
 
-SDK 1.0.18 | Plugin API 1.10.0
+SDK 1.0.20 | Plugin API 1.12.0
 
 This guide is for anyone, person or AI coding tool, building a Termix plugin. It ships inside
 `@termix-ssh/plugin-sdk`, so the copy in your `node_modules` always matches the SDK you have installed.
@@ -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)     |
@@ -642,6 +643,9 @@ exports with props is `ui.api.txt` in the Termix repo
   `PanePrompt` for small prompts.
 - Every tab or panel sits in `PanelShell`. Lists use `PanelList` and `ListRow`, add with `AddButton`,
   forms end with `FormFooter`, empty lists show `EmptyState`.
+- Card grids use `DataView` with `ViewToggle`. Pass `columns` and `onColumns` to `ViewToggle` and the same
+  value as `size` to `DataView`, so users can pick Auto (as many as fit) or a fixed number of cards per
+  row. `usePluginPanelView` keeps the choice as `columns`. Older Termix versions ignore both props.
 - Forms: `TextField`, `NumberField`, `SelectField`, `SwitchRow`, `SecretField`, `SettingRow` and friends.
 - Host sessions use `ConnectionGate` for the whole connect flow (host keys, TOTP, passphrases, errors).
 - Mobile: check `useIsMobile()` and give small screens a layout that works. The desktop app always uses the

package/dist/desktop.d.ts

@@ -33,6 +33,15 @@ export interface ElectronAPI {
     getAppVersion: () => Promise<string>;
     setZoomFactor?: (factor: number) => void;
     getPlatform: () => Promise<string>;
+    /** Whether the app-drawn title bar shows in this window. */
+    getTitleBarVisible?: () => Promise<boolean>;
+    /** Calls back when the title bar shows or hides; returns an unsubscribe. */
+    onTitleBarVisibleChange?: (callback: (visible: boolean) => void) => () => void;
+    /** Keeps the window controls the system draws in the colors of the theme. */
+    setTitleBarOverlay?: (colors: {
+        color?: string;
+        symbolColor?: string;
+    }) => Promise<void>;
     getSetting?: (key: string) => Promise<string | null | undefined>;
     setSetting?: (key: string, value: string) => Promise<void>;
     getServerConfig: () => Promise<ServerConfig>;

package/dist/frontend.d.ts

@@ -783,6 +783,24 @@ export interface CompanionDefaults {
     /** Show the edge button that opens and closes it. Default true. */
     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;
@@ -1044,6 +1062,11 @@ export interface TermixApp extends TermixAppInfo {
      * it; the tab keeps running underneath.
      */
     registerCompanion: (id: string, 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: (section: HostEditorSectionContribution) => Disposer;
@@ -1220,6 +1243,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[];
@@ -1402,17 +1426,21 @@ export declare function usePluginUiPreferences<T extends Record<string, unknown>
     values: T;
     set: <K extends keyof T & string>(key: K, value: T[K] | null) => void;
 };
+type PanelGridSize = "auto" | "1" | "2" | "3" | "4" | "5" | "6";
 /**
- * Grid or list and row density for one of this plugin's views, kept in its
- * Appearance area as `<prefix>viewMode` and `<prefix>density`. Declare those
- * keys in contributes.uiPresets so each preset level can pick a default.
+ * Grid or list, row density and cards per row for one of this plugin's
+ * views, kept in its Appearance area as `<prefix>viewMode`, `<prefix>density`
+ * and `<prefix>columns`. Declare those keys in contributes.uiPresets so each
+ * preset level can pick a default. Hand columns to ViewToggle and DataView.
  */
 export declare function usePluginPanelView(prefix?: string): {
     view: "grid" | "list";
     density: "comfortable" | "compact";
     compact: boolean;
+    columns: PanelGridSize;
     setView: (view: "grid" | "list") => void;
     setDensity: (density: "comfortable" | "compact") => void;
+    setColumns: (columns: PanelGridSize) => void;
 };
 export declare function useTabs(): TabsApi;
 /**
@@ -1445,6 +1473,11 @@ export declare function useSlotContributions(slotId: string, context?: Record<st
  * connect widget, say. Reactive: it re-renders as plugins enable and disable.
  */
 export declare function useHostActions(): HostActionContribution[];
+/**
+ * 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 declare function useCompanions(tabType: string): CompanionInfo[];
 /**
  * Recent-activity types every registered tab claims (registerTab's
  * activityTypes), core's and plugins'. For a filter that lists what a user

package/dist/frontend.js

@@ -165,21 +165,37 @@ export function usePluginUiPreferences() {
     const bridge = requireHost();
     return bridge.usePluginUiPreferences(bridge.usePluginId());
 }
+const PANEL_GRID_SIZES = [
+    "auto",
+    "1",
+    "2",
+    "3",
+    "4",
+    "5",
+    "6",
+];
 /**
- * Grid or list and row density for one of this plugin's views, kept in its
- * Appearance area as `<prefix>viewMode` and `<prefix>density`. Declare those
- * keys in contributes.uiPresets so each preset level can pick a default.
+ * Grid or list, row density and cards per row for one of this plugin's
+ * views, kept in its Appearance area as `<prefix>viewMode`, `<prefix>density`
+ * and `<prefix>columns`. Declare those keys in contributes.uiPresets so each
+ * preset level can pick a default. Hand columns to ViewToggle and DataView.
  */
 export function usePluginPanelView(prefix = "") {
     const { values, set } = usePluginUiPreferences();
     const view = values[`${prefix}viewMode`] === "list" ? "list" : "grid";
     const density = values[`${prefix}density`] === "compact" ? "compact" : "comfortable";
+    const saved = values[`${prefix}columns`];
+    const columns = typeof saved === "string" && PANEL_GRID_SIZES.includes(saved)
+        ? saved
+        : "auto";
     return {
         view,
         density,
         compact: density === "compact",
+        columns,
         setView: (next) => set(`${prefix}viewMode`, next),
         setDensity: (next) => set(`${prefix}density`, next),
+        setColumns: (next) => set(`${prefix}columns`, next),
     };
 }
 export function useTabs() {
@@ -220,6 +236,13 @@ export function useSlotContributions(slotId, context) {
 export function useHostActions() {
     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) {
+    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

package/dist/host/{PluginsTab-YAGYRBIE.js → PluginsTab-ZSMTJ5C5.js}

@@ -29,7 +29,7 @@ import {
   sortPlugins,
   uploadEntry,
   youtubeEmbedUrl
-} from "./chunk-446UEDSK.js";
+} from "./chunk-CITUENSU.js";
 import {
   ArrowDownWideNarrow,
   BookOpen,
@@ -38,7 +38,6 @@ import {
   Check,
   ChevronLeft,
   ChevronRight,
-  Columns3,
   DEVELOPER_MODE_CHANGED_EVENT,
   Database,
   DocsLink,
@@ -47,6 +46,7 @@ import {
   Facts,
   FakeSwitch,
   FlaskConical,
+  GRID_SIZES,
   Globe,
   GroupHeading,
   InlineView,
@@ -107,7 +107,7 @@ import {
   updatePlugin,
   uploadPlugin,
   useConfirm
-} from "./chunk-LQKK2JJA.js";
+} from "./chunk-EYONBBRJ.js";
 import "./chunk-7LEJ3HYF.js";
 import {
   __toESM,
@@ -1845,7 +1845,6 @@ function usePluginsManager() {
 
 // src/ui/plugins/PluginsTab.tsx
 import { Fragment as Fragment4, jsx as jsx6, jsxs as jsxs6 } from "react/jsx-runtime";
-var GRID_SIZES = ["auto", "2", "3", "4", "5", "6"];
 function useStoredChoice(key, allowed, fallback) {
   const [value, setValue] = useState5(() => {
     try {
@@ -2075,45 +2074,15 @@ function LayoutControls({
   onView,
   onColumns
 }) {
-  const { t } = useTranslation7();
-  return /* @__PURE__ */ jsxs6(Fragment4, { children: [
-    layout.view === "grid" && /* @__PURE__ */ jsxs6(
-      Select,
-      {
-        value: layout.columns,
-        onValueChange: (v) => onColumns(v),
-        children: [
-          /* @__PURE__ */ jsxs6(
-            SelectTrigger,
-            {
-              size: "sm",
-              className: "w-auto gap-1.5 text-xs",
-              title: t("plugins.manager.columns.title"),
-              "aria-label": t("plugins.manager.columns.title"),
-              children: [
-                /* @__PURE__ */ jsx6(Columns3, { className: "size-3.5 text-muted-foreground" }),
-                /* @__PURE__ */ jsx6(SelectValue, {})
-              ]
-            }
-          ),
-          /* @__PURE__ */ jsx6(SelectContent, { children: GRID_SIZES.map((size) => /* @__PURE__ */ jsx6(SelectItem, { value: size, className: "text-xs", children: size === "auto" ? t("plugins.manager.columns.auto") : t("plugins.manager.columns.count", { count: Number(size) }) }, size)) })
-        ]
-      }
-    ),
-    /* @__PURE__ */ jsx6(ViewToggle, { view: layout.view, onView })
-  ] });
-}
-function gridStyle(columns) {
-  if (columns === "auto") {
-    return {
-      gridTemplateColumns: "repeat(auto-fill, minmax(min(100%, 400px), 1fr))"
-    };
-  }
-  const n = Number(columns);
-  const gaps = (n - 1) * 12;
-  return {
-    gridTemplateColumns: `repeat(auto-fill, minmax(max(220px, calc((100% - ${gaps}px) / ${n} - 0.5px)), 1fr))`
-  };
+  return /* @__PURE__ */ jsx6(
+    ViewToggle,
+    {
+      view: layout.view,
+      onView,
+      columns: layout.columns,
+      onColumns
+    }
+  );
 }
 function PluginCollection({
   plugins,
@@ -2137,7 +2106,20 @@ function PluginCollection({
       }
     );
   }
-  return /* @__PURE__ */ jsx6("div", { className: "grid gap-3", style: gridStyle(layout.columns), children: plugins.map((p) => /* @__PURE__ */ jsx6("div", { className: "flex flex-col *:flex-1", children: renderCard(p) }, p.id)) });
+  return /* @__PURE__ */ jsx6(
+    DataView,
+    {
+      items: plugins,
+      view: "grid",
+      getKey: (p) => p.id,
+      renderCard,
+      columns: {},
+      size: layout.columns,
+      minCardWidth: 400,
+      listColumns,
+      empty: null
+    }
+  );
 }
 function NameCell({ plugin, muted }) {
   return /* @__PURE__ */ jsxs6("div", { className: "flex min-w-0 items-center gap-2", children: [

package/dist/host/{chunk-446UEDSK.js → chunk-CITUENSU.js}

@@ -6,8 +6,9 @@ import {
   Plus,
   Trash,
   cn,
+  gridSizeStyle,
   useAreaPreferences
-} from "./chunk-LQKK2JJA.js";
+} from "./chunk-EYONBBRJ.js";
 import {
   isElectron
 } from "./chunk-7LEJ3HYF.js";
@@ -2219,6 +2220,8 @@ function DataView({
   getKey,
   renderCard,
   columns,
+  size,
+  minCardWidth,
   listColumns,
   onRowClick,
   isRowActive,
@@ -2229,7 +2232,19 @@ function DataView({
     return /* @__PURE__ */ jsx3("div", { className: "flex flex-1 items-center justify-center", children: empty });
   }
   if (view === "grid") {
-    return /* @__PURE__ */ jsx3("div", { className: cn("grid", PANEL.gap, gridClass(columns), className), children: items.map((item) => /* @__PURE__ */ jsx3("div", { children: renderCard(item) }, getKey(item))) });
+    return /* @__PURE__ */ jsx3(
+      "div",
+      {
+        className: cn(
+          "grid",
+          PANEL.gap,
+          !size && gridClass(columns),
+          className
+        ),
+        style: size ? gridSizeStyle(size, minCardWidth) : void 0,
+        children: items.map((item) => /* @__PURE__ */ jsx3("div", { className: "flex flex-col *:flex-1", children: renderCard(item) }, getKey(item)))
+      }
+    );
   }
   const template = listColumns.map((c) => c.width).join(" ");
   const rowHeight = density === "compact" ? "h-7" : "h-9";