From 36d04863923e0d299d16c30f111ea3a2d9851cb1 Mon Sep 17 00:00:00 2001 From: Luke Parker <10430890+Hona@users.noreply.github.com> Date: Fri, 6 Nov 2026 04:21:04 +1000 Subject: [PATCH] feat(plugin): add a sidebar.section slot for plugin sections in the sidebar --- .../component-tests/plugin-host.fixture.tsx | 58 ++++++++ .../app/component-tests/plugin-host.spec.ts | 134 +++++++++++++++++- packages/app/src/shell/shell.tsx | 13 +- .../src/shell/titlebar/sidebar-sections.tsx | 32 +++++ packages/app/src/shell/titlebar/titlebar.tsx | 4 +- packages/gui-plugins/README.md | 37 ++--- packages/plugin/src/gui/registries.ts | 15 ++ .../docs/content/build/plugins/gui/index.mdx | 25 +++- 8 files changed, 298 insertions(+), 20 deletions(-) create mode 100644 packages/app/src/shell/titlebar/sidebar-sections.tsx diff --git a/packages/app/component-tests/plugin-host.fixture.tsx b/packages/app/component-tests/plugin-host.fixture.tsx index e54ccb77587..5a47cf9d877 100644 --- a/packages/app/component-tests/plugin-host.fixture.tsx +++ b/packages/app/component-tests/plugin-host.fixture.tsx @@ -52,6 +52,7 @@ import { persistedHandle } from "../src/runtime/plugin/stores" import { LanguageProvider } from "../src/runtime/i18n/language" import { ExtensionPlugins } from "../src/runtime/plugin/extension-plugins" import { SessionPluginPills } from "../src/session/composer/plugin-pills" +import { SidebarSections } from "../src/shell/titlebar/sidebar-sections" import { ui } from "../src/runtime/plugin/ui" export { @@ -826,6 +827,63 @@ export function mountComposerPills(input: { definitions: readonly Entry[] }) { } } +/** + * Mounts the real host and the sidebar's production `sidebar.section` slot in a sidebar column 240 by 600 pixels, under + * a list that fills the rest, as the vertical tabs sidebar holds it. `show(false)` collapses the sidebar; `disable` + * turns plugins off as Extensions › Plugins does. + */ +export function mountSidebarSections(input: { definitions: readonly Entry[] }) { + const container = document.createElement("div") + container.dataset.testid = "sidebar" + container.style.cssText = "display: flex; flex-direction: column; width: 240px; height: 600px" + document.body.appendChild(container) + const hosts: PluginHost[] = [] + const [shown, setShown] = createSignal(true) + const [disabled, setDisabled] = createSignal>(new Set()) + + function Sidebar() { + const host = usePluginHost() + hosts.push(host) + + return ( + +
+ + + ) + } + + const dispose = render( + () => ( + + + input.definitions} + disabled={disabled} + apis={fakeApis(unused)} + whenMounted={mounted} + > + + + + + ), + container, + ) + + return { + container, + show: (value: boolean) => setShown(value), + disable: (ids: readonly string[]) => setDisabled(new Set(ids)), + status: (id: string) => hosts[0]?.status(id), + failure: (id: string) => hosts[0]?.failure(id), + unmount: () => { + dispose() + container.remove() + }, + } +} + /** * Mounts the real host and one message's production Markdown inside the session screen's `PluginLinks`, for a session * whose directory is `/repo`. `show(text, streaming)` replaces the message as a stream does; `define` replaces the diff --git a/packages/app/component-tests/plugin-host.spec.ts b/packages/app/component-tests/plugin-host.spec.ts index 3a5fb6b5b4f..61ef4a405de 100644 --- a/packages/app/component-tests/plugin-host.spec.ts +++ b/packages/app/component-tests/plugin-host.spec.ts @@ -9,11 +9,12 @@ import type { Live, SessionRef, SessionScreen, + SlotMap, } from "@opencode/plugin/gui" import type { BuiltinPanelTab } from "@opencode/plugin/gui/builtin" import type { Bridge, BridgeMessage, EnableState, Installed } from "@opencode/plugin/gui/host" import type { JSHandle } from "@playwright/test" -import type { mountCodeBlocks, mountThemes } from "./plugin-host.fixture" +import type { mountCodeBlocks, mountSidebarSections, mountThemes } from "./plugin-host.fixture" import { expect, sourceURL, story } from "../../stories/playwright/story" const fixture = sourceURL(new URL("./plugin-host.fixture.tsx", import.meta.url)) @@ -21,6 +22,9 @@ const fixture = sourceURL(new URL("./plugin-host.fixture.tsx", import.meta.url)) /** What the code block cases drive from the page. */ type CodeBlocksHost = ReturnType +/** What the sidebar section cases drive from the page. */ +type SidebarHost = ReturnType + /** What the theme preview case drives from the page. */ type ThemesHost = ReturnType @@ -985,6 +989,134 @@ story("a contribution that throws renders nothing and records the error; the oth }) }) +story( + "sidebar sections render in order under the list, stay mounted while the sidebar collapses, and leave no box without them", + async ({ page }) => { + const result = await page.evaluate(async (fixture) => { + const { mountSidebarSections, until, Slot } = await import(fixture) + const renders = { count: 0 } + + const host: SidebarHost = mountSidebarSections({ + definitions: [ + { + id: "fixture", + windowEntry: async () => ({ + default: (ctx: Context) => { + ctx.add(Slot, { + at: "sidebar.section", + order: 2, + render: () => Object.assign(document.createElement("p"), { textContent: "pinned" }), + }) + ctx.add(Slot, { + at: "sidebar.section", + order: 1, + render: (input: SlotMap["sidebar.section"]) => { + renders.count++ + + return () => (input.shown ? "shown" : "hidden") + }, + }) + ctx.add(Slot, { + at: "sidebar.section", + order: 3, + render: () => Object.assign(document.createElement("div"), { style: "height: 1000px; flex: none" }), + }) + }, + }), + }, + ], + }) + + const sections = () => host.container.querySelector('[data-slot="sidebar-sections"]') + await until(() => !!sections()?.textContent) + const box = sections()!.getBoundingClientRect() + const list = host.container.querySelector('[data-testid="list"]')!.getBoundingClientRect() + const frame = host.container.getBoundingClientRect() + + const placed = { + text: sections()!.textContent, + underList: box.top >= list.bottom && Math.abs(box.bottom - frame.bottom) < 1, + half: box.height <= frame.height / 2 && sections()!.scrollHeight > sections()!.clientHeight, + } + + host.show(false) + await until(() => sections()?.textContent === "hiddenpinned") + const collapsed = { text: sections()?.textContent, renders: renders.count } + + host.show(true) + await until(() => sections()?.textContent === "shownpinned") + host.disable(["fixture"]) + await until(() => host.status("fixture") === "disabled") + const outcome = { placed, collapsed, renders: renders.count, left: sections() === null } + + host.unmount() + + return outcome + }, fixture) + + expect(result).toEqual({ + placed: { text: "shownpinned", underList: true, half: true }, + collapsed: { text: "hiddenpinned", renders: 1 }, + renders: 1, + left: true, + }) + }, +) + +story( + "a sidebar section that throws renders nothing and records the error; the other sections stay", + async ({ page }) => { + const result = await page.evaluate(async (fixture) => { + const { mountSidebarSections, until, Slot } = await import(fixture) + const text = (value: string) => () => Object.assign(document.createElement("p"), { textContent: value }) + + const host: SidebarHost = mountSidebarSections({ + definitions: [ + { + id: "fixture", + windowEntry: async () => ({ + default: (ctx: Context) => { + ctx.add(Slot, { + at: "sidebar.section", + render: () => { + throw new Error("broken section") + }, + }) + ctx.add(Slot, { at: "sidebar.section", render: text("kept") }) + }, + }), + }, + { + id: "other", + windowEntry: async () => ({ + default: (ctx: Context) => void ctx.add(Slot, { at: "sidebar.section", render: text("other") }), + }), + }, + ], + }) + + await until(() => !!host.failure("fixture") && !!host.container.textContent?.includes("other")) + const failure = host.failure("fixture") + + const outcome = { + text: host.container.querySelector('[data-slot="sidebar-sections"]')?.textContent, + status: [host.status("fixture"), host.status("other")], + failure: { phase: failure?.phase, named: !!failure?.error.includes("broken section") }, + } + + host.unmount() + + return outcome + }, fixture) + + expect(result).toEqual({ + text: "keptother", + status: ["active", "active"], + failure: { phase: "render", named: true }, + }) + }, +) + story( "plugin GUIs join, hot-reload in place, run their returned cleanup and leave, without holding startup", async ({ page }) => { diff --git a/packages/app/src/shell/shell.tsx b/packages/app/src/shell/shell.tsx index 0312e34b843..92012b2cd22 100644 --- a/packages/app/src/shell/shell.tsx +++ b/packages/app/src/shell/shell.tsx @@ -228,7 +228,18 @@ export default function Layout(props: ParentProps) { : "max(0px, calc(8px - var(--safe-area-inset-bottom, env(safe-area-inset-bottom, 0px))))", }} > - +
{/* The empty inset above the panels moves the window, as the titlebar does. */} diff --git a/packages/app/src/shell/titlebar/sidebar-sections.tsx b/packages/app/src/shell/titlebar/sidebar-sections.tsx new file mode 100644 index 00000000000..cd408f6babe --- /dev/null +++ b/packages/app/src/shell/titlebar/sidebar-sections.tsx @@ -0,0 +1,32 @@ +import { createMemo, Show } from "solid-js" +import { BuiltinSlot } from "@opencode/plugin/gui/builtin" +import { usePluginHost } from "@/runtime/plugin/host" +import { PluginSlot } from "@/runtime/plugin/render" + +/** + * The `sidebar.section` slot under the sidebar's list. Absent while nothing contributes; otherwise it takes at most half + * the sidebar's height and scrolls past it, so a tall section never pushes the list out. + */ +export function SidebarSections(props: { shown: boolean }) { + const host = usePluginHost() + const contributed = createMemo(() => host.items(BuiltinSlot).some((item) => item.value.at === "sidebar.section")) + + return ( + +
+ +
+
+ ) +} diff --git a/packages/app/src/shell/titlebar/titlebar.tsx b/packages/app/src/shell/titlebar/titlebar.tsx index 114b3954fea..00f1cdc9715 100644 --- a/packages/app/src/shell/titlebar/titlebar.tsx +++ b/packages/app/src/shell/titlebar/titlebar.tsx @@ -19,6 +19,7 @@ import { TitlebarTabStrip } from "@/shell/titlebar/tab-strip" import { macVerticalTrafficLights, SidebarToggle } from "@/shell/sidebar-toggle" import { SidebarInbox } from "@/shell/titlebar/inbox" import { SidebarOrganized } from "@/shell/titlebar/sidebar-organized" +import { SidebarSections } from "@/shell/titlebar/sidebar-sections" import { makeEventListener } from "@solid-primitives/event-listener" import { createMediaQuery } from "@solid-primitives/media" import { readSessionTabsRemovedDetail, SESSION_TABS_REMOVED_EVENT } from "@/shell/titlebar/session-events" @@ -68,7 +69,7 @@ const macTrafficLightsTopClearance = 28 // titlebar row stays 16px clear of it, as ChatGPT's phone header does. Without one, 8px matches the content gap below. const mobileTopClearance = "max(8px, min(16px, env(safe-area-inset-top, 0px) * 1000))" -export function Titlebar(props: { verticalTabs?: { mount?: HTMLElement } }) { +export function Titlebar(props: { verticalTabs?: { mount?: HTMLElement; shown: boolean } }) { const platform = usePlatform() const command = useCommand() const language = useLanguage() @@ -803,6 +804,7 @@ export function Titlebar(props: { verticalTabs?: { mount?: HTMLElement } }) {
+ 0}>
diff --git a/packages/gui-plugins/README.md b/packages/gui-plugins/README.md index d3a685c55af..7c151f17343 100644 --- a/packages/gui-plugins/README.md +++ b/packages/gui-plugins/README.md @@ -252,28 +252,33 @@ SDK icon fields take an `IconName` from `@opencode/plugin/gui`: the names of the ### Registries -| Registry | Process | What an item is | -| ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`Command`](../plugin/src/gui/registries.ts) | window | A palette command with an optional keybind and slash command | -| [`MenuItem`](../plugin/src/gui/registries.ts) | window | An item of a host menu: the side panel + menu, Add server, a server row | -| [`Panel`](../plugin/src/gui/registries.ts) | window | Tabs in the session's side region | -| [`SettingsPage`](../plugin/src/gui/registries.ts) | window | A settings page, a section on a host page, or rows in a host section | -| [`Server`](../plugin/src/gui/registries.ts) | window | A source of servers, such as SSH hosts | -| [`LinkHandler`](../plugin/src/gui/registries.ts) | window | Opens local links, such as file paths in messages, and says whether their target exists | -| [`TitlebarItem`](../plugin/src/gui/registries.ts) | window | A pill in the titlebar or the tabs footer | -| [`ComposerPill`](../plugin/src/gui/registries.ts) | window | A pill in the row above a session's composer, optionally opening a menu of rows or a popover of your own content | -| [`CodeBlock`](../plugin/src/gui/registries.ts) | window | Your UI in place of the highlighted code of complete fenced code blocks of the languages you list, such as a diagram or a table | -| [`CodeBlockAction`](../plugin/src/gui/registries.ts) | window | A button beside the Copy button of complete fenced code blocks of the languages you list, such as "Run in terminal" | -| [`Slot`](../plugin/src/gui/registries.ts) | window | Content for `window.bottom`, `session.header`, `session.location.menu`, `session.panel.end`; built-ins also fill `session.location.workspace`, `session.location.branch.menu` and `session.location.path.menu` through `BuiltinSlot` | -| [`Style`](../plugin/src/gui/registries.ts) | window | CSS imported with `?inline` | -| [`Theme`](../plugin/src/gui/registries.ts) | window | A color theme in the app's theme file format, listed in Settings › Appearance › Theme | -| [`MenubarItem`](../plugin/src/gui/main.ts) | main | An item of the native app menu | +| Registry | Process | What an item is | +| ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`Command`](../plugin/src/gui/registries.ts) | window | A palette command with an optional keybind and slash command | +| [`MenuItem`](../plugin/src/gui/registries.ts) | window | An item of a host menu: the side panel + menu, Add server, a server row | +| [`Panel`](../plugin/src/gui/registries.ts) | window | Tabs in the session's side region | +| [`SettingsPage`](../plugin/src/gui/registries.ts) | window | A settings page, a section on a host page, or rows in a host section | +| [`Server`](../plugin/src/gui/registries.ts) | window | A source of servers, such as SSH hosts | +| [`LinkHandler`](../plugin/src/gui/registries.ts) | window | Opens local links, such as file paths in messages, and says whether their target exists | +| [`TitlebarItem`](../plugin/src/gui/registries.ts) | window | A pill in the titlebar or the tabs footer | +| [`ComposerPill`](../plugin/src/gui/registries.ts) | window | A pill in the row above a session's composer, optionally opening a menu of rows or a popover of your own content | +| [`CodeBlock`](../plugin/src/gui/registries.ts) | window | Your UI in place of the highlighted code of complete fenced code blocks of the languages you list, such as a diagram or a table | +| [`CodeBlockAction`](../plugin/src/gui/registries.ts) | window | A button beside the Copy button of complete fenced code blocks of the languages you list, such as "Run in terminal" | +| [`Slot`](../plugin/src/gui/registries.ts) | window | Content for `window.bottom`, `session.header`, `session.location.menu`, `session.panel.end`, `sidebar.section`; built-ins also fill `session.location.workspace`, `session.location.branch.menu` and `session.location.path.menu` through `BuiltinSlot` | +| [`Style`](../plugin/src/gui/registries.ts) | window | CSS imported with `?inline` | +| [`Theme`](../plugin/src/gui/registries.ts) | window | A color theme in the app's theme file format, listed in Settings › Appearance › Theme | +| [`MenubarItem`](../plugin/src/gui/main.ts) | main | An item of the native app menu | `session.location.menu` contributes items after the project menu's location details. It receives the owning `screen`, the live `session`, and `shown`; keep data subscriptions active only while `shown` is true. Loading headers without an owning screen show the host's location details without this slot. Render its rows with `ctx.ui.MenuItem`, `ctx.ui.MenuSub`, `ctx.ui.MenuGroup` and `ctx.ui.MenuSeparator`, so they navigate and close like the host's rows. +`sidebar.section` adds a section to the app's sidebar (not the inner sidebar of side panels), under its list and above +its footer pills. Only the Side tabs and Inbox layouts in windows 768px and wider have that sidebar; elsewhere the slot +renders nothing. Sections stay mounted while the sidebar is collapsed, with `shown` false, so pause polling then. +Together they take at most half the sidebar's height and scroll past it. + `session.location.branch.menu` (built-ins only, through `BuiltinSlot`) contributes items after Copy branch name in the branch submenu, with the same `screen`, live `session`, and project-menu `shown` context. It renders only when a branch name and owning screen are available. Use it for actions on the branch's working directory, such as opening diff --git a/packages/plugin/src/gui/registries.ts b/packages/plugin/src/gui/registries.ts index 09481f4dabf..78574f24b57 100644 --- a/packages/plugin/src/gui/registries.ts +++ b/packages/plugin/src/gui/registries.ts @@ -897,6 +897,21 @@ export interface SlotMap { /** The routed session; a new object when another session is routed. */ readonly session: MountedSession } + /** + * Sections of the app's sidebar, the list of projects, sessions and tabs at the window's start: under that list and + * above the sidebar's footer pills. Not the inner sidebar of side panels (`Layout.sidebar`). Only the Side tabs and + * Inbox interface layouts have this sidebar, in windows 768px and wider: with Top tabs, and on narrow screens where + * tabs open in a drawer, the slot renders nothing. Contributions stay mounted while the user collapses the sidebar. + * Together they take at most half the sidebar's height and scroll past it. Read the routed session from + * `Sessions.current`; the slot shows on Home and drafts too. + */ + readonly "sidebar.section": { + /** + * The sidebar is on screen: docked open, or peeking while collapsed. False while it is collapsed, where your section + * stays mounted but hidden; pause polling and subscriptions until it is true again. + */ + readonly shown: boolean + } } /** Content for one of the host's slots, typed by `at`. */ diff --git a/services/www/src/docs/content/build/plugins/gui/index.mdx b/services/www/src/docs/content/build/plugins/gui/index.mdx index 4adbbfacd92..b629d6d7e68 100644 --- a/services/www/src/docs/content/build/plugins/gui/index.mdx +++ b/services/www/src/docs/content/build/plugins/gui/index.mdx @@ -996,7 +996,7 @@ interface SettingEntry { ### Slots -`Slot` renders UI into one of four window slots. +`Slot` renders UI into one of the window's slots. ```tsx import { Slot } from "@opencode/plugin/gui" @@ -1013,6 +1013,8 @@ ctx.add(Slot, { `false`. - `session.location.menu` adds items to the project menu, after its location details. - `session.panel.end` holds actions at the trailing end of the side region's tab strip. +- `sidebar.section` adds a section to the app's sidebar, under its list of projects, sessions, and tabs. See + [Sidebar sections](#sidebar-sections). - `order` sorts the items in one slot. `session.location.menu` receives `shown`, which is `true` while the project menu is open. Subscribe to location data @@ -1035,6 +1037,26 @@ ctx.add(Slot, { }) ``` +#### Sidebar sections + +`sidebar.section` adds a section, such as pinned sessions or a status block, to the sidebar at the start of the window. +It shows under the sidebar's list and above its footer pills. + +```tsx +ctx.add(Slot, { + at: "sidebar.section", + render: (input) => , +}) +``` + +- The sidebar exists only with the **Side tabs** and **Inbox** interface layouts, in windows 768px and wider. With + **Top tabs**, and on narrow screens where tabs open in a drawer, the slot renders nothing. +- When the user collapses the sidebar, your section stays mounted and `shown` is `false`. It is `true` while the + sidebar is open, or while it peeks out on hover. Pause polling and subscriptions while `shown` is `false`. +- All sections together take at most half the sidebar's height. Taller content scrolls. +- The slot also shows on Home and on drafts. Read the routed session from `ctx.sessions.current()`. +- This is not the inner sidebar that side panels share (`ctx.layout.sidebar`). + #### Reference ```ts @@ -1047,6 +1069,7 @@ interface SlotMap { "session.header": { screen: SessionScreen; session: MountedSession; active: boolean } "session.location.menu": { screen: SessionScreen; session: MountedSession; shown: boolean } "session.panel.end": { screen: SessionScreen; session: MountedSession } + "sidebar.section": { shown: boolean } } ```