wings-plugin-sdk 0.0.0-stage → 0.2.0

package/ui.js

@@ -0,0 +1,290 @@
+// wings-plugin-sdk/ui: a page says what to show and where, and Wings decides how it looks. Every component renders
+// plain elements with `w-*` class names and data attributes that Wings' plugin-ui.css styles, never a style of its
+// own, so a Wings update restyles every plugin. Your own components and CSS work alongside them.
+import { createContext, createElement as h, useContext, useEffect, useId, useState } from "react";
+import { createRoot } from "react-dom/client";
+
+import { mountShell } from "./shell.js";
+
+export { mountShell } from "./shell.js";
+export { useBroadcast } from "./react.js";
+
+// ---------- places ----------
+
+let root = null;
+
+function show(place, element, options) {
+  const shell = mountShell(place, options);
+  root ??= createRoot(shell);
+  root.render(element);
+}
+
+/** Shows `element` as the page of a sidebar. One call per page; calling again renders the new element. */
+export const showSidebar = (element, options) => show("sidebar", element, options);
+/** Shows `element` as a view's page, in a modal or a window of its own. */
+export const showView = (element, options) => show("view", element, options);
+/** Shows `element` as a view's page in a tab next to the terminals. */
+export const showTab = (element, options) => show("tab", element, options);
+/** Shows `element` as a sidebar's popover. */
+export const showPopover = (element, options) => show("popover", element, options);
+/** Shows `element` as the plugin's page in Wings Settings. */
+export const showSettings = (element, options) => show("settings", element, options);
+
+// ---------- talking to main ----------
+
+const HELLO = { type: "hello" };
+
+/**
+ * The newest message of `type` the plugin's other pages broadcast, or null until one comes. Sends `hello` once
+ * when the component mounts, so main answers with its state; pass null to send nothing.
+ */
+export function useMainState(type, hello = HELLO) {
+  const [state, setState] = useState(null);
+  useEffect(() => {
+    const off = wings.onBroadcast((message) => {
+      if (message?.type === type) setState(message);
+    });
+    if (hello != null) void wings.broadcast(hello);
+    return off;
+    // `hello` is only sent when the component mounts.
+  }, [type]);
+  return state;
+}
+
+// ---------- helpers ----------
+
+const cx = (base, extra) => (extra ? `${base} ${extra}` : base);
+/** A data attribute that's there or not. */
+const flag = (on) => (on ? "" : undefined);
+
+// ---------- layout and text ----------
+
+/** Children side by side, centred. `gap` is none, xs, s, m (default) or l. */
+export function Row({ as = "div", gap, align, justify, wrap, grow, className, ...rest }) {
+  return h(as, { ...rest, className: cx("w-row", className), "data-gap": gap, "data-align": align, "data-justify": justify, "data-wrap": flag(wrap), "data-grow": flag(grow) });
+}
+
+/** Children one under the other. */
+export function Stack({ as = "div", gap, grow, className, ...rest }) {
+  return h(as, { ...rest, className: cx("w-stack", className), "data-gap": gap, "data-grow": flag(grow) });
+}
+
+/** Text with a tone and size, that can grow to fill a row or truncate with an ellipsis. */
+export function Text({ as = "span", tone, size, weight, mono, numeric, truncate, clamp, grow, className, ...rest }) {
+  return h(as, {
+    ...rest,
+    className: cx("w-text", className),
+    "data-tone": tone,
+    "data-size": size,
+    "data-weight": weight,
+    "data-mono": flag(mono),
+    "data-numeric": flag(numeric),
+    "data-truncate": flag(truncate),
+    "data-clamp": flag(clamp),
+    "data-grow": flag(grow),
+  });
+}
+
+/** A section heading, with `actions` like chips or a button on its right. */
+export function Heading({ actions, className, ...rest }) {
+  const heading = h("h2", { ...rest, className: cx("w-heading", className) });
+  return actions ? h("div", { className: "w-heading-row" }, heading, actions) : heading;
+}
+
+/** A card. `compact` for a summary line. */
+export function Card({ as = "div", compact, className, ...rest }) {
+  return h(as, { ...rest, className: cx("w-card", className), "data-size": compact ? "compact" : undefined });
+}
+
+// ---------- figures ----------
+
+const levelTone = (percent, levels) => (!levels ? undefined : percent >= levels[1] ? "danger" : percent >= levels[0] ? "warn" : undefined);
+
+/** A bar from 0 to 100. `tone` is warn or danger. */
+export function Meter({ percent, label, tone, className, ...rest }) {
+  return h(
+    "div",
+    { ...rest, className: cx("w-meter", className), role: "meter", "aria-label": label, "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": percent, "data-tone": tone },
+    // How full it is is data, not a style: plugin-ui.css sizes the bar from it.
+    h("span", { className: "w-meter-fill", style: { "--w-value": `${Math.max(0, Math.min(100, percent))}%` } }),
+  );
+}
+
+/** A labelled bar with its percentage and a note under it. `levels` are where it turns warn and danger. */
+export function Gauge({ label, percent, note, tone, levels, className, ...rest }) {
+  return h(
+    "div",
+    { ...rest, className: cx("w-gauge", className) },
+    h("span", { className: "w-gauge-label" }, label),
+    h("span", { className: "w-gauge-value" }, `${percent}%`),
+    h(Meter, { percent, label, tone: tone ?? levelTone(percent, levels) }),
+    note ? h("span", { className: "w-gauge-note" }, note) : null,
+  );
+}
+
+/** Small figures side by side, label over value. */
+export function Stats({ items, className, ...rest }) {
+  return h(
+    "dl",
+    { ...rest, className: cx("w-stats", className) },
+    items.map((item) => h("div", { key: item.label }, h("dt", { className: "w-stat-label" }, item.label), h("dd", { className: "w-stat-value", "data-tone": item.tone, title: item.title }, item.value))),
+  );
+}
+
+/** Label and value pairs, one per line. */
+export function Properties({ items, className, ...rest }) {
+  return h(
+    "dl",
+    { ...rest, className: cx("w-props", className) },
+    items.map((item) => h("div", { key: item.label, className: "w-prop" }, h("dt", { className: "w-prop-label" }, item.label), h("dd", { className: "w-prop-value" }, item.value))),
+  );
+}
+
+// ---------- lists ----------
+
+/** A list of rows. `ordered` for an `ol`, `compact` for rows with no space between them. */
+export function List({ ordered, compact, className, ...rest }) {
+  return h(ordered ? "ol" : "ul", { ...rest, className: cx("w-list", className), "data-density": compact ? "compact" : undefined });
+}
+
+/** A row in a `List`. Holding a `ListButton`, the button is the row. */
+export function ListItem({ align, className, ...rest }) {
+  return h("li", { ...rest, className: cx("w-list-item", className), "data-align": align });
+}
+
+/** A row that's a button, inside a `ListItem`. */
+export function ListButton({ align, type = "button", className, ...rest }) {
+  return h("button", { ...rest, type, className: cx("w-list-button", className), "data-align": align });
+}
+
+// ---------- status ----------
+
+/** A status dot. With a `label` it's announced; otherwise it's decoration next to text that says the same. */
+export function Dot({ tone, label, className, ...rest }) {
+  return h("span", { ...rest, className: cx("w-dot", className), "data-tone": tone, ...(label ? { role: "img", "aria-label": label } : { "aria-hidden": true }) });
+}
+
+/** A spinner. With a `label` it's announced. */
+export function Spinner({ size, label, className, ...rest }) {
+  return h("span", { ...rest, className: cx("w-spinner", className), "data-size": size, ...(label ? { role: "img", "aria-label": label } : { "aria-hidden": true }) });
+}
+
+/** A filled pill, like a label on a command. */
+export function Pill({ tone, className, ...rest }) {
+  return h("span", { ...rest, className: cx("w-pill", className), "data-tone": tone });
+}
+
+/** An outlined tag, like a branch name. */
+export function Tag({ tone, className, ...rest }) {
+  return h("span", { ...rest, className: cx("w-tag", className), "data-tone": tone });
+}
+
+/** What shows before the first data comes. */
+export function Loading({ children = "Loading…", className, ...rest }) {
+  return h("p", { ...rest, className: cx("w-loading", className) }, children);
+}
+
+/** Nothing to show: what's missing, and a `detail` line on what to do about it. */
+export function Empty({ title, detail, className, ...rest }) {
+  return h("div", { ...rest, className: cx("w-empty", className) }, h("p", null, title), detail === undefined ? null : h("p", { className: "w-empty-detail" }, detail));
+}
+
+// ---------- buttons ----------
+
+/** A button. `variant` is primary, ghost or danger; `size` small. */
+export function Button({ variant, size, type = "button", className, ...rest }) {
+  return h("button", { ...rest, type, className: cx("w-button", className), "data-variant": variant, "data-size": size });
+}
+
+/** A small quiet button. With `pressed` it's a toggle. */
+export function Chip({ pressed, type = "button", className, ...rest }) {
+  return h("button", { ...rest, type, className: cx("w-chip", className), "aria-pressed": pressed });
+}
+
+/** Chips that pick one of `options`, like a filter. `onChange` gets each click, the chip that's on too. */
+export function Chips({ label, options, value, onChange, className, ...rest }) {
+  return h(
+    "div",
+    { ...rest, className: cx("w-chips", className), role: "group", "aria-label": label },
+    options.map((o) => h(Chip, { key: o.value, pressed: o.value === value, title: o.title, onClick: () => onChange(o.value) }, o.label)),
+  );
+}
+
+/** Tabs over the panel they show, `children`. Arrow keys, Home and End move between tabs. */
+export function Tabs({ label, items, value, onChange, children, className, ...rest }) {
+  const id = useId();
+  const tabId = (v) => `${id}-tab-${v}`;
+  const onKeyDown = (e) => {
+    const at = items.findIndex((t) => t.value === value);
+    const next = { ArrowRight: at + 1, ArrowLeft: at - 1, Home: 0, End: items.length - 1 }[e.key];
+    if (next === undefined) return;
+    e.preventDefault();
+    const tab = items[(next + items.length) % items.length];
+    onChange(tab.value);
+    document.getElementById(tabId(tab.value))?.focus();
+  };
+  return h(
+    "div",
+    { ...rest, className },
+    h(
+      "div",
+      { className: "w-tabs", role: "tablist", "aria-label": label, onKeyDown },
+      items.map((t) =>
+        h("button", { key: t.value, type: "button", id: tabId(t.value), className: "w-tab", role: "tab", "aria-selected": t.value === value, "aria-controls": `${id}-panel`, tabIndex: t.value === value ? 0 : -1, onClick: () => onChange(t.value) }, t.label),
+      ),
+    ),
+    h("div", { id: `${id}-panel`, role: "tabpanel", "aria-labelledby": tabId(value) }, children),
+  );
+}
+
+// ---------- fields ----------
+
+const FieldContext = createContext(null);
+
+/** Gives an input in a `Field` its label and hint. */
+function useFieldProps(rest) {
+  const field = useContext(FieldContext);
+  return field ? { id: field.id, "aria-describedby": field.hint, "aria-invalid": field.invalid || undefined, ...rest } : rest;
+}
+
+/** A labelled field with a `hint` or an `error` under it, for the input in `children`. */
+export function Field({ label, hint, error, children, className, ...rest }) {
+  const id = useId();
+  const note = error ?? hint;
+  return h(
+    "div",
+    { ...rest, className: cx("w-field", className) },
+    h("label", { className: "w-field-label", htmlFor: id }, label),
+    h(FieldContext.Provider, { value: { id, hint: note ? `${id}-hint` : undefined, invalid: Boolean(error) } }, children),
+    note ? h("p", { id: `${id}-hint`, className: "w-field-hint", "data-tone": error ? "danger" : undefined }, note) : null,
+  );
+}
+
+/** A text input. Outside a `Field`, give it a `label`. */
+export function TextInput({ label, type = "text", className, ...rest }) {
+  return h("input", { "aria-label": label, ...useFieldProps(rest), type, className: cx("w-input", className) });
+}
+
+/** A search box. `label` names it for screen readers. */
+export function SearchField({ label, className, ...rest }) {
+  return h("input", { "aria-label": label, ...useFieldProps(rest), type: "search", className: cx("w-search", className) });
+}
+
+/** A select of `options`. `onChange` gets the value picked. */
+export function Select({ label, options, onChange, className, ...rest }) {
+  return h(
+    "select",
+    { "aria-label": label, ...useFieldProps(rest), className: cx("w-select", className), onChange: (e) => onChange?.(e.currentTarget.value) },
+    options.map((o) => h("option", { key: o.value, value: o.value, disabled: o.disabled }, o.label)),
+  );
+}
+
+/** A checkbox with its label, `children`. `onChange` gets whether it's checked. */
+export function Checkbox({ onChange, children, className, ...rest }) {
+  return h("label", { className: cx("w-check", className) }, h("input", { ...rest, type: "checkbox", onChange: (e) => onChange?.(e.currentTarget.checked) }), children);
+}
+
+/** More behind a `summary` line that opens it. */
+export function Disclosure({ summary, children, className, ...rest }) {
+  return h("details", { ...rest, className: cx("w-disclosure", className) }, h("summary", null, summary), children);
+}

package/wings.d.ts

@@ -0,0 +1,225 @@
+// Types for the Wings plugin SDK, API 1. `window.wings` exists in every plugin; this file only helps your editor.
+// In TypeScript, add "wings-plugin-sdk" to `types` in tsconfig.json. In JavaScript, start a file with
+// `// @ts-check` and `/// <reference types="wings-plugin-sdk" />`.
+
+type Tone = "neutral" | "info" | "success" | "warning" | "danger" | "merged";
+
+interface WingsPane {
+  paneId: string;
+  /** Follows `cd` in the pane. */
+  cwd: string;
+  /** What runs in the pane right now, like `zsh` or `claude`. */
+  command: string;
+  project: string;
+  /** Set while Claude Code runs in the pane. `startedAt` is when that `claude` started, in ms; a resumed session's transcript also has what came before. */
+  session: { sessionId: string; name: string | null; state: string; startedAt: number } | null;
+  /** The focused pane of the tab on screen. At most one pane has it, and none while no tab is open. */
+  focused: boolean;
+}
+
+interface WingsTranscriptEvent {
+  sessionId: string;
+  /** The pane the session runs in. */
+  paneId: string;
+  /** The entry as Claude Code wrote it. Its `type` is one of `permissions.transcript`. */
+  entry: { type: string } & Record<string, unknown>;
+}
+
+interface WingsBadge {
+  label: string;
+  tone: Tone;
+  icon?: "pr-open" | "pr-merged" | "pr-closed" | "pr-draft";
+  /** Small icon-and-number chips after the label. Leave out zeros. */
+  counts?: { icon: "changed" | "push" | "pull"; value: number }[];
+  /** Shows a spinner in the pill. */
+  loading?: boolean;
+  title?: string;
+  subtitle?: string;
+  rows?: { label: string; value: string; tone?: Tone }[];
+  actions?: { id: string; label: string; primary?: boolean }[];
+}
+
+interface WingsComment {
+  id: number;
+  replyTo: number | null;
+  /** `null` for a comment on the whole change. */
+  path: string | null;
+  /** `null` when the comment no longer matches the diff. */
+  line: number | null;
+  side: "additions" | "deletions";
+  author: string;
+  body: string;
+  createdAt: string;
+  url: string;
+  /** On the first comment of a thread: the viewer offers a reply box, and sends replies to `onReply`. */
+  canReply?: boolean;
+}
+
+/** A reply typed in the diff viewer. `replyTo` is the id of the thread's first comment. */
+interface WingsReply {
+  diffId: string;
+  replyTo: number;
+  body: string;
+}
+
+/** A usage limit window. `resetsAt` is in Unix epoch seconds. */
+interface WingsLimitWindow {
+  usedPercentage: number;
+  resetsAt: number | null;
+}
+
+/** What Claude Code last told `wings statusline`. `at` is when Wings got it, in ms. */
+interface WingsStatusline {
+  /** Your account's 5-hour and weekly limits, from the newest session that reported them. `null` until one has. */
+  rateLimits: { fiveHour: WingsLimitWindow | null; sevenDay: WingsLimitWindow | null; at: number } | null;
+  /** By session id. Token counts are from the session's last API response. */
+  sessions: Record<
+    string,
+    {
+      /** Like `Opus 5.5 (1M context)`. */
+      model: string | null;
+      contextWindowSize: number | null;
+      usedPercentage: number | null;
+      totalInputTokens: number | null;
+      totalOutputTokens: number | null;
+      currentUsage: { inputTokens: number; outputTokens: number; cacheCreationInputTokens: number; cacheReadInputTokens: number } | null;
+      /** `expiresAt` is in Unix epoch seconds. */
+      promptCache: { warm: boolean; ttl: "5m" | "1h" | null; expiresAt: number | null } | null;
+      at: number;
+    }
+  >;
+}
+
+interface WingsExecOptions {
+  cwd?: string;
+  /** 30 s by default, 5 min at most. */
+  timeoutMs?: number;
+  /** Gets each stdout and stderr line while the program runs. */
+  onOutput?: (line: string) => void;
+}
+
+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;
+  /**
+   * A badge action was clicked. Return a promise: the button spins until it settles (up to 5 min), and a thrown
+   * error shows in the card. What it resolves to is ignored.
+   */
+  onAction(listener: (action: { paneId: string; actionId: string }) => unknown): () => void;
+  /**
+   * Handles Claude's calls to a tool in `contributes.mcpTools`. Return a string or a JSON value; a thrown error
+   * is sent back as a failed call. `paneId` is the Wings pane Claude runs in, or `null`. Register it in `main`.
+   */
+  onTool(name: string, handler: (input: Record<string, unknown>, context: { paneId: string | null }) => unknown): void;
+  /** Runs a command from `permissions.exec`, like `git branch --show-current`. */
+  exec(program: string, args?: string[], options?: WingsExecOptions): Promise<{ code: number | null; stdout: string; stderr: string }>;
+  /**
+   * Needs `permissions.statusline`. What Claude Code last told its status line, once `wings statusline` is your
+   * `statusLine` command: usage limits and each session's context and cache, as Claude Code reports them.
+   */
+  statusline(): Promise<WingsStatusline>;
+  /** Claude Code transcript entries of types in `permissions.transcript`, oldest first. */
+  transcript(sessionId: string, types: string[], options?: { last?: number }): Promise<Record<string, unknown>[]>;
+  /**
+   * Each transcript entry Claude Code writes while it runs in a pane, for the types in `permissions.transcript`.
+   * Only entries written after the plugin started, or after the session started in the pane; `transcript` reads
+   * earlier ones. Entries over 256 KB are skipped.
+   */
+  onTranscript(listener: (event: WingsTranscriptEvent) => void): () => void;
+  /** Needs `"badges"` in `contributes.ui`. `null` removes it. */
+  setBadge(paneId: string, badge: WingsBadge | null): Promise<void>;
+  /**
+   * Needs `permissions.ports`. The local TCP ports the programs in your panes listen on, that `localhost`
+   * reaches. About 20 ms a call, so poll slowly.
+   */
+  ports(): Promise<{ paneId: string; pid: number; name: string; port: number; startedAt: number }[]>;
+  /** Opens an https URL, or an http one to localhost, 127.0.0.1 or [::1], that starts with a prefix in `permissions.openUrl`. */
+  openUrl(url: string): Promise<void>;
+  /**
+   * Needs `permissions.panes`. Opens a terminal in a new tab, or a split beside the focused pane, and resolves
+   * once the pane is in `onPanes`. `command`, like `"npm run dev"`, is typed into its shell and must start with
+   * an entry of `permissions.panes`. `cwd` must be inside one of your projects; without it the pane opens at the
+   * root of the project on screen.
+   */
+  openPane(options?: { command?: string; cwd?: string; placement?: "tab" | "right" | "down" }): Promise<{ paneId: string }>;
+  /** Needs `permissions.panes`. Shows an open pane and moves the keyboard to it. */
+  focusPane(paneId: string): Promise<void>;
+  /**
+   * After `exec` rejected with "<program> is not installed or not on PATH": Wings asks you, installs it in a new tab
+   * and restarts the plugin once it's there. Only `az`, `gh` and `glab`, and only ones `permissions.exec` names.
+   * Resolves true once the install started (or it's already installed), false if you cancelled.
+   */
+  installTool(program: "az" | "gh" | "glab"): Promise<boolean>;
+  /** Needs `permissions.notify`. A desktop notification, up to 3 a minute. The title is cut at 64 characters, the body at 256. */
+  notify(notification: { title: string; body?: string }): Promise<void>;
+  /** Needs `"diff"` in `contributes.ui`. Leave out `patch` to open it loading, then call `updateDiff`. */
+  openDiff(diff: { title: string; subtitle?: string; patch?: string; comments?: WingsComment[] }): Promise<{ id: string }>;
+  /** Updates a viewer opened with `openDiff`; ignored once it's closed. `{ comments }` alone keeps the patch, like after a reply. */
+  updateDiff(id: string, update: { patch: string; comments?: WingsComment[] } | { comments: WingsComment[] } | { error: string }): Promise<void>;
+  /**
+   * Needs `"diff"` in `contributes.ui`. A reply typed under a comment with `canReply` in the diff viewer. Post it,
+   * then add it with `updateDiff`. The reply box waits for the returned promise, and a thrown error shows under it
+   * with the text kept. One handler: a second call replaces the first.
+   */
+  onReply(handler: (reply: WingsReply) => unknown): void;
+  /**
+   * POSTs `fields` (string or whole-number values, up to 64 KB) as JSON to a `permissions.post` path, as you:
+   * `gh api`, `glab api` against `host`, or `az rest` for Azure DevOps. Wings builds the command itself.
+   */
+  post(
+    program: "gh" | "glab" | "az",
+    url: string,
+    fields: Record<string, string | number>,
+    options?: { host?: string },
+  ): Promise<{ code: number | null; stdout: string; stderr: string }>;
+  /**
+   * An HTTP request to a URL under `permissions.fetch`, made by Wings. `bearer` names a secret that Wings sends
+   * as `Authorization: Bearer <secret>`. Resolves for any status; redirects aren't followed.
+   */
+  fetch(
+    url: string,
+    init?: { method?: string; headers?: Record<string, string>; body?: string; bearer?: string },
+  ): Promise<{ status: number; contentType: string | null; body: string }>;
+  /** Secrets, like API tokens, in the system keychain. `fetch` can send them, but they can't be read back. */
+  secrets: {
+    set(name: string, value: string): Promise<void>;
+    delete(name: string): Promise<void>;
+    has(name: string): Promise<boolean>;
+  };
+  /**
+   * The plugin's own storage for settings and state, since `localStorage` throws in plugin pages. Values are
+   * JSON. Keys are 1 to 128 letters, digits and `- _ . : /`, and it holds 1 MB in all. Only this plugin sees it.
+   */
+  storage: {
+    /** The value, or `null` when the key isn't set. */
+    get(key: string): Promise<unknown>;
+    /** Refused if it would take the plugin's storage over 1 MB. */
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Every key, sorted. */
+    keys(): Promise<string[]>;
+  };
+  /** Short text next to a sidebar's or view's title bar button, like a running timer. `null` clears it. */
+  setSidebarLabel(sidebarId: string, label: string | null, options?: { rows?: { label: string; value: string }[]; tone?: "warning" | "danger" }): Promise<void>;
+  /**
+   * Opens one of `contributes.sidebars` or `contributes.views` by id: in the right sidebar, in a modal over Wings,
+   * in a window of its own or as a tab in the project on screen (`tab` needs Wings 0.1.15). `as` must be in the
+   * view's `opens`, and defaults to the first. A window or tab that's already open comes to the front. The page
+   * gets the same `wings` object wherever it opens.
+   */
+  openView(id: string, options?: { as?: "sidebar" | "modal" | "window" | "tab" }): Promise<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. */
+  openSettings(): Promise<void>;
+  /** Sends a JSON value, up to 64 KB, to the plugin's other pages: its main script and open sidebars, modals and windows. */
+  broadcast(message: unknown): Promise<void>;
+  /** Gets what the plugin's other pages send with `broadcast`. */
+  onBroadcast(listener: (message: unknown) => void): () => void;
+}
+
+declare const wings: Wings;
+
+/** A page's own CSS, `import "./sidebar.css"`: wings-plugin build bundles it into the page's `<name>.css`. */
+declare module "*.css";