wings-plugin-sdk 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wings-plugin-sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "The wings API types, the page frame, React hooks and the build command for Wings plugins.",
   "license": "MIT",
   "type": "module",
@@ -26,6 +26,9 @@
       "default": "./build.mjs"
     }
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "bin": {
     "wings-plugin": "bin.mjs"
   },
@@ -69,8 +72,5 @@
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "typescript": "~6.0.3"
-  },
-  "scripts": {
-    "test": "node --test"
   }
-}
+}

package/wings.d.ts

@@ -108,13 +108,28 @@ interface WingsProject {
   branch: string | null;
 }
 
+/** A line in a plugin's section under a project in the sidebar. Needs Wings 0.1.23. */
+interface WingsProjectSectionRow {
+  /** Up to 64 characters, unique in the section. */
+  id: string;
+  /** Up to 120 characters. */
+  label: string;
+  /** Muted text under the label, up to 120 characters. */
+  detail?: string;
+  /** A small pill after the label. `text` is up to 24 characters. */
+  badge?: { text: string; tone?: Tone };
+  /** Clicking the row opens `view`, one of the plugin's `contributes.views` that lists `tab` in `opens`, as a tab in the row's project, with `args` (JSON, up to 16 KB) as `viewArgs()`. */
+  open: { view: string; args?: unknown };
+}
+
 interface Wings {
   // Every `on*` call returns a function that removes the listener, for cleaning up in a React effect.
   /** Every terminal pane, on every change. */
   onPanes(listener: (panes: WingsPane[]) => void): () => void;
   /**
    * Whether the user is in Wings: true while any Wings window (the main one or a view window) is in front, false
-   * while another app is. Called once with the current state, then on each change. Needs no permission. Pause timers
+   * while another app is. In a block on a Project page it is also false while the block is out of view or its tab is hidden.
+   * Called once with the current state, then on each change. Needs no permission. Pause timers
    * while it is false and check once when it turns true, or use `pollWhileFocused` from `wings-plugin-sdk/poll`.
    */
   onFocus(listener: (event: { focused: boolean }) => void): () => void;
@@ -227,16 +242,16 @@ interface Wings {
    * gets the same `wings` object wherever it opens.
    *
    * `args` (JSON, up to 16 KB, only with `as: "tab"`) is what the tab's page reads with `viewArgs`. A tab that's
-   * already open with other args takes the new ones, drops its saved tab state and reloads; a view with `"multiple": true` always opens a
-   * new tab. Needs Wings 0.1.22.
+   * already open with other args takes the new ones, drops its saved tab state and reloads; a view with `"multiple": true` opens a new tab,
+   * unless a tab of it in that project already has the same `args`: that one is shown. Needs Wings 0.1.22.
    */
   openView(id: string, options?: { as?: "sidebar" | "modal" | "window" | "tab"; args?: unknown }): Promise<void>;
   /** Where this page shows. `null` in the plugin's main script. Needs Wings 0.1.22. */
-  placement(): "sidebar" | "tab" | "modal" | "window" | null;
+  placement(): "sidebar" | "tab" | "modal" | "window" | "block" | null;
   /** What `openView` passed as `args` when it opened this tab, or `null`. Available at once. Needs Wings 0.1.22. */
   viewArgs<T = unknown>(): T | null;
   /**
-   * The project this page is about, or `null` when none is open. A tab page's project is the one the tab belongs to
+   * The project this page is about, or `null` when none is open. A tab page's or block's project is the one it belongs to
    * and never changes; any other page gets the project on screen. Needs Wings 0.1.22.
    */
   project(): Promise<WingsProject | null>;
@@ -245,6 +260,20 @@ interface Wings {
    * tab page), or its branch or name changed. Needs Wings 0.1.22.
    */
   onProject(listener: (project: WingsProject | null) => void): () => void;
+  /** Every project in Wings, in sidebar order. Worktrees are projects too. Needs Wings 0.1.23. */
+  projects(): Promise<WingsProject[]>;
+  /**
+   * Calls the listener with every project, then each time one is added, removed or renamed, or a branch changes.
+   * Works in the main script and in pages. Needs Wings 0.1.23.
+   */
+  onProjects(listener: (projects: WingsProject[]) => void): () => void;
+  /**
+   * Shows `rows` under a project in the sidebar, in the section `sectionId` that the manifest declares in
+   * `contributes.projectSections`, or removes the section with `null`. Up to 50 rows. Rejects for a project that isn't
+   * there, a section the plugin didn't declare, or a row whose `open.view` isn't one of its views that opens as a tab.
+   * Sections are kept in memory and go when the plugin is turned off, so fill them again on start. Needs Wings 0.1.23.
+   */
+  setProjectSection(projectId: string, sectionId: string, rows: WingsProjectSectionRow[] | null): Promise<void>;
   /** In a tab page: the state it last saved with `setTabState`, or `null`. Outside a tab it is `null`. Opening the tab with new `args` clears it. Needs Wings 0.1.22. */
   tabState<T = unknown>(): Promise<T | null>;
   /**
@@ -252,6 +281,23 @@ interface Wings {
    * unloaded. Rejects outside a tab or when the state is too big. Needs Wings 0.1.22.
    */
   setTabState(state: unknown): Promise<void>;
+  /**
+   * In a block on a Project page, `contributes.blocks`: the state it last saved with `setBlockState`, or `null`. Outside a
+   * block it is `null`. Needs Wings 0.1.24.
+   */
+  blockState<T = unknown>(): Promise<T | null>;
+  /**
+   * In a block: saves JSON state, up to 16 KB, on the block, like which board or filter it shows. Wings keeps it with the
+   * Project page across restarts and while the block is unloaded. Rejects outside a block or when the state is too big.
+   * Needs Wings 0.1.24.
+   */
+  setBlockState(state: unknown): Promise<void>;
+  /**
+   * In a block: asks for a height in CSS pixels. Wings rounds it and clamps it to the block's `minHeight` (default 160)
+   * up to 1200, and applies it without reloading the page. Call it when the content's height changes: asking for the
+   * height already asked for does nothing, and calls in the same tick send only the last. Throws outside a block. Needs Wings 0.1.24.
+   */
+  setHeight(px: number): void;
   /** Closes a sidebar or view wherever it's open. */
   closeView(id: string): Promise<void>;
   /** Opens Wings Settings at the plugin's settings page, `contributes.settings`. Wings 0.1.15 and newer. */