feat(plugin): add a sidebar.section slot for plugin sections in the sidebar

This commit is contained in:
Luke Parker
2026-11-06 04:21:04 +10:00
Unverified
parent 174200d95e
commit 36d0486392
8 changed files with 298 additions and 20 deletions
@@ -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<ReadonlySet<string>>(new Set())
function Sidebar() {
const host = usePluginHost()
hosts.push(host)
return (
<Show when={host.ready()}>
<div data-testid="list" style={{ flex: "1", "min-height": "0" }} />
<SidebarSections shown={shown()} />
</Show>
)
}
const dispose = render(
() => (
<LanguageProvider locale="en">
<DialogProvider>
<PluginHostProvider
definitions={() => input.definitions}
disabled={disabled}
apis={fakeApis(unused)}
whenMounted={mounted}
>
<Sidebar />
</PluginHostProvider>
</DialogProvider>
</LanguageProvider>
),
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
@@ -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<typeof mountCodeBlocks>
/** What the sidebar section cases drive from the page. */
type SidebarHost = ReturnType<typeof mountSidebarSections>
/** What the theme preview case drives from the page. */
type ThemesHost = ReturnType<typeof mountThemes>
@@ -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<HTMLElement>('[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 }) => {
+12 -1
View File
@@ -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))))",
}}
>
<Titlebar verticalTabs={verticalTabs() ? { mount: state.tabsMount } : undefined} />
<Titlebar
verticalTabs={
verticalTabs()
? {
mount: state.tabsMount,
get shown() {
return preferences.appearance.sidebarOpen() || peek.shown()
},
}
: undefined
}
/>
<div class="relative flex flex-1 min-h-0 min-w-0 flex-row">
{/* The empty inset above the panels moves the window, as the titlebar does. */}
<Show when={dragInset()}>
@@ -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 (
<Show when={contributed()}>
<div
data-slot="sidebar-sections"
data-scrollable
class="mt-2 flex max-h-[50%] min-h-0 w-full shrink-0 flex-col gap-2 overflow-y-auto"
>
<PluginSlot
at="sidebar.section"
input={{
get shown() {
return props.shown
},
}}
/>
</div>
</Show>
)
}
+3 -1
View File
@@ -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 } }) {
<SidebarInbox />
</Show>
</div>
<SidebarSections shown={vertical().shown} />
<Show when={titlebarItems.ids().length > 0}>
<div data-slot="vertical-tabs-footer" class="mt-2 flex w-full shrink-0 flex-col">
<TitlebarItems items={titlebarItems} vertical />
+21 -16
View File
@@ -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
+15
View File
@@ -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`. */
@@ -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) => <Pinned shown={input.shown} current={ctx.sessions.current()?.key} />,
})
```
- 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 }
}
```