feat(app): let GUI plugin panels size the side region (#61509)

This commit is contained in:
Luke Parker
2026-11-03 16:45:52 -06:00
committed by GitHub
Unverified
parent 4dd7b2662c
commit 69ef55f02b
11 changed files with 340 additions and 19 deletions
@@ -40,6 +40,8 @@ import { createHostApis } from "../src/runtime/plugin/host-apis"
import { createInstalled } from "../src/runtime/plugin/installed"
import { pluginEnabled, type Entry } from "@opencode/plugin/gui/host"
import { createRegion, RegionContent } from "../src/runtime/plugin/panels"
import { createSessionScreenLayout } from "../src/session/screen-layout"
import type { SessionModel } from "../src/session/model"
import { createClosedTabs } from "../src/runtime/plugin/closed-tabs"
import { PluginSlot, PluginThemes } from "../src/runtime/plugin/render"
import { ThemeProvider, useTheme } from "@opencode/ui/theme/context"
@@ -86,7 +88,7 @@ const layout: BuiltinLayout = {
hide() {},
state: () => "closed",
stored: () => [],
side: { opened: () => false, toggle() {}, menu: () => [] },
side: { opened: () => false, toggle() {}, menu: () => [], width: () => undefined, resize() {} },
sidebar: { opened: () => true },
scroll: { get: () => undefined, set() {} },
settings() {},
@@ -382,7 +384,7 @@ function standIn(overrides: Partial<Interface>): Interface {
hide() {},
state: () => "closed",
stored: () => [],
side: { opened: () => true, toggle() {}, menu: () => [] },
side: { opened: () => true, toggle() {}, menu: () => [], width: () => undefined, resize() {} },
sidebar: { opened: () => false },
scroll: { get: () => undefined, set() {} },
},
@@ -423,6 +425,124 @@ function RealHost(props: ParentProps<{ definitions: readonly Entry[]; captured:
)
}
/**
* Mounts the real host, the side region and the session screen's layout in a row `width` pixels wide, with every
* panel's `main` tab stored. `select(key)` selects a tab as the user does; `drag(width)` drags the divider to that chat
* panel width, once `handle()` shows the row is measured. The chat panel (`data-testid="chat"`) takes the width the
* layout gives it. The conversation's own width
* and the per-panel widths are in-memory stores, read back through `conversation()` and `widths()`.
*/
export function mountPanelWidths(input: { definitions: readonly Entry[]; active: string; width: number }) {
const container = document.createElement("div")
document.body.appendChild(container)
const captured: Captured = {}
const [active, setActive] = createSignal(input.active)
const [conversation, setConversation] = createStore<{ width: number; resized: boolean }>({
width: 600,
resized: false,
})
const [widths, setWidths] = createStore<Record<string, number>>({})
const layouts: ReturnType<typeof createSessionScreenLayout>[] = []
const value = { key: "fixture\na", id: "a", tab: "a", pending: false, location: { directory: "/repo" }, visit: {} }
// SAFETY: the region passes the session through; the test's plugins read nothing of it.
// oxlint-disable-next-line anti-slop/no-chained-type-assertions -- see SAFETY above
const view = () => value as unknown as MountedSession
// SAFETY: the test's plugins never read the screen.
// oxlint-disable-next-line anti-slop/no-chained-type-assertions -- see SAFETY above
const screen = {} as unknown as SessionScreen
const model = {
isDesktop: () => true,
identity: { params: { id: "a" } },
layout: {
view: () => ({
side: { opened: () => true },
session: {
width: () => conversation.width,
resized: () => conversation.resized,
resize: (width: number) => setConversation({ width, resized: true }),
},
}),
},
}
// SAFETY: the screen layout reads only `isDesktop`, `identity.params.id` and the view's side and session fields.
// oxlint-disable-next-line anti-slop/no-chained-type-assertions -- see SAFETY above
const session = model as unknown as SessionModel
function Screen() {
const host = usePluginHost()
const all = () => host.items(Panel).map((item) => `${item.plugin}:main`)
const region = createRegion({
region: "side",
view,
screen,
tabs: () => ({
tabs: () => ({ all: all(), active: active() }),
all,
active,
setAll() {},
setActive: (key) => key && setActive(key),
close() {},
remap() {},
}),
closed: createClosedTabs(),
open() {},
side: () => ({ opened: () => true, toggle() {} }),
})
const layout = createSessionScreenLayout(session, {
wide: region.wide,
panel: region.pane("side").selected,
widths: { get: (panel) => widths[panel], set: (panel, width) => setWidths(panel, width) },
})
layouts.push(layout)
return (
<div ref={layout.panel.ref} style={{ display: "flex", gap: "8px", width: `${input.width}px` }}>
<div data-testid="chat" style={{ "flex-shrink": "0", width: layout.panel.width() }} />
<div data-testid="side" style={{ flex: "1" }} />
</div>
)
}
const dispose = render(
() => (
<LanguageProvider locale="en">
<PlatformProvider value={web}>
<DialogProvider>
<RealHost definitions={input.definitions} captured={captured}>
<Screen />
</RealHost>
</DialogProvider>
</PlatformProvider>
</LanguageProvider>
),
container,
)
return {
select: (key: string) => setActive(key),
drag: (width: number) => layouts[0]?.panel.resize(width),
/** The chat panel width the divider's handle starts a drag from, once the row is measured. */
handle: () => layouts[0]?.panel.resizedWidth(),
chat: () => container.querySelector<HTMLElement>('[data-testid="chat"]')?.getBoundingClientRect().width,
conversation: () => ({ ...conversation }),
widths: () => ({ ...widths }),
unmount: () => {
dispose()
container.remove()
},
}
}
/**
* Mounts the real host and HostApis, and the parts of the session screen that render plugin content for the routed
* session: the side region (`createRegion`, `RegionContent`) with every panel's tabs stored, and the
@@ -1529,6 +1529,64 @@ story("a selected plugin theme that never returns shows the default theme once p
})
})
story(
"a panel with a width of its own sizes the side region and keeps the width the user drags it to",
async ({ page }) => {
const result = await page.evaluate(async (fixture) => {
const { mountPanelWidths, until, Panel } = await import(fixture)
const panel = (id: string, width?: "narrow") => ({
id: `${id}-plugin`,
windowEntry: async () => ({
default: (ctx: Context) =>
void ctx.add(Panel, {
id,
region: "side",
width,
list: (input: { open: readonly string[] }) =>
input.open.includes("main") ? [{ id: "main", title: id }] : [],
render: () => null,
}),
}),
})
// The row is 1200px wide: the chat panel and the side region share 1192px beside the 8px gap.
const host = mountPanelWidths({
definitions: [panel("quota", "narrow"), panel("files")],
active: "quota-plugin:main",
width: 1200,
})
// The chat panel is on screen at this width, and the divider's handle starts a drag from it.
const settle = (width: number) => until(() => host.chat() === width && host.handle() === width)
// `narrow` leaves the side region its minimum, 320px.
await settle(872)
host.drag(700)
await settle(700)
const dragged = { widths: host.widths(), conversation: host.conversation() }
// A panel without a width keeps the conversation's, and a drag on it changes only that.
host.select("files-plugin:main")
await settle(600)
host.drag(650)
await settle(650)
const shared = { widths: host.widths(), conversation: host.conversation() }
host.select("quota-plugin:main")
await settle(700)
host.unmount()
return { dragged, shared }
}, fixture)
expect(result).toEqual({
dragged: { widths: { "quota-plugin:quota": 492 }, conversation: { width: 600, resized: false } },
shared: { widths: { "quota-plugin:quota": 492 }, conversation: { width: 650, resized: true } },
})
},
)
story("composer pills show per session, open their rows, and fail only their own plugin", async ({ page }) => {
const statuses = await page.evaluate(async (fixture) => {
const { mountComposerPills, until, ComposerPill } = await import(fixture)
@@ -80,8 +80,10 @@ type Attached = {
scope: (server: string) => ServerScope
/** Records a session-scoped store so layout pruning drops it with the session. */
scoped: (name: string) => void
layout: Omit<Layout, "narrow" | "settings" | "project" | "draft" | "command" | "stored"> & {
layout: Omit<Layout, "narrow" | "settings" | "project" | "draft" | "command" | "stored" | "side"> & {
stored(plugin: string, session: SessionRef): readonly string[]
/** `width` and `resize` take the panel's host key, `${plugin}:${panel id}`. */
side: Layout["side"]
}
settings: (page?: string) => void
project: (server: string, title: string) => void
@@ -411,6 +413,8 @@ export function createHostApis() {
opened: (session) => current()?.layout.side.opened(session) ?? false,
toggle: (session) => write((value) => value.layout.side.toggle(session)),
menu: () => current()?.layout.side.menu() ?? [],
width: (panel) => current()?.layout.side.width(`${plugin}:${panel}`),
resize: (panel, width) => write((value) => value.layout.side.resize(`${plugin}:${panel}`, width)),
},
sidebar: { opened: () => current()?.layout.sidebar.opened() ?? true },
scroll: {
@@ -1097,6 +1101,8 @@ export function createPluginAttachment(apis: HostApis) {
opened: sideOpened,
toggle: (session) => tabs.setRegion(shellTab(session), "side", !sideOpened(session)),
menu,
width: layout.panelWidth.get,
resize: layout.panelWidth.set,
},
// Open is the stored preference's default, which holds until a session screen shows the preference.
sidebar: { opened: () => sidebar()?.opened() ?? true },
+61 -8
View File
@@ -3,14 +3,45 @@ import { createStore } from "solid-js/store"
import { createResizeObserver } from "@solid-primitives/resize-observer"
import { createSizing } from "./helpers"
import type { SessionModel } from "./model"
import { clampSessionPanelWidth, sessionPanelWidthCss, sessionPanelWidthMax } from "./session-panel-width"
import type { RegionEntry } from "@/runtime/plugin/panels"
import { panelKey } from "@/runtime/plugin/panel-keys"
import {
clampSessionPanelWidth,
SIDE_PANE_WIDTH_MIN,
sessionPanelWidthCss,
sessionPanelWidthMax,
sidePanelWidthCss,
} from "./session-panel-width"
/** wide asks for the wider session minimum. */
export function createSessionScreenLayout(session: SessionModel, input: { wide: Accessor<boolean> }) {
/** Side region widths of panels that size themselves, by `${plugin}:${panel id}`. */
export type PanelWidths = { get(panel: string): number | undefined; set(panel: string, width: number): void }
/**
* wide asks for the wider session minimum. panel is the tab the side pane shows: while its panel has a width of its
* own (stored in widths, else `Panel.width`), that width sizes the side region and a drag stores it there.
*/
export function createSessionScreenLayout(
session: SessionModel,
input: { wide: Accessor<boolean>; panel: Accessor<RegionEntry | undefined>; widths: PanelWidths },
) {
const size = createSizing()
const view = session.layout.view
const tabsOpen = createMemo(() => session.isDesktop() && view().side.opened() && !!session.identity.params.id)
const sized = createMemo(() => {
const entry = input.panel()
if (!entry) return
const key = panelKey(entry.plugin, entry.provider.id)
const width =
input.widths.get(key) ?? (entry.provider.width === "narrow" ? SIDE_PANE_WIDTH_MIN : entry.provider.width)
if (width === undefined) return
return { width, resize: (next: number) => input.widths.set(key, next) }
})
const [rowSize, setRowSize] = createStore<{ width?: number }>({})
let row: HTMLDivElement | undefined
createResizeObserver(
@@ -28,17 +59,31 @@ export function createSessionScreenLayout(session: SessionModel, input: { wide:
const splitSide = createMemo(() => tabsOpen() && input.wide())
const resizedWidth = createMemo(() =>
clampSessionPanelWidth({
const resizedWidth = createMemo(() => {
const current = sized()
const width = available()
if (current && width !== undefined)
return clampSessionPanelWidth({
width: width - Math.max(SIDE_PANE_WIDTH_MIN, current.width),
available: width,
split: splitSide(),
resized: true,
})
return clampSessionPanelWidth({
width: view().session.width(),
available: available(),
available: width,
split: splitSide(),
resized: view().session.resized(),
}),
)
})
})
const panelWidth = createMemo(() => {
if (!tabsOpen()) return "100%"
const current = sized()
if (current) return sidePanelWidthCss(current.width)
return sessionPanelWidthCss({
width: view().session.width(),
@@ -80,6 +125,14 @@ export function createSessionScreenLayout(session: SessionModel, input: { wide:
resizable: tabsOpen,
resizedWidth,
width: panelWidth,
/** A drag to this chat panel width: the shown panel keeps the side width it leaves, else the conversation does. */
resize(width: number) {
const current = sized()
const space = available()
if (current && space !== undefined) return current.resize(space - width)
view().session.resize(width)
},
},
side: {
contentWidth: sideContentWidth,
+7 -2
View File
@@ -21,6 +21,7 @@ import { ComposerDropzone } from "@/composer/dropzone"
import { useSettings } from "@/settings/model"
import type { SessionModel } from "@/session/model"
import { SESSION_PANEL_WIDTH_MIN } from "@/session/session-panel-width"
import { useLayout } from "@/shell/state/layout"
import { SessionPanelFrame } from "@/session/session-frame"
import { PluginLinks } from "@/runtime/plugin/render"
import { createPanelSidebar, createRegion, MobilePanel } from "@/runtime/plugin/panels"
@@ -118,7 +119,11 @@ function SessionScreenContent(props: {
}),
})
const screen = createSessionScreenLayout(session, { wide: region.wide })
const screen = createSessionScreenLayout(session, {
wide: region.wide,
panel: region.pane("side").selected,
widths: useLayout().panelWidth,
})
const timeline = createSessionTimelineInteraction(session)
@@ -505,7 +510,7 @@ function SessionScreenContent(props: {
max={screen.panel.max()}
onResize={(width) => {
screen.size.touch()
session.layout.view().session.resize(width)
screen.panel.resize(width)
}}
onDraggingChange={setPanelResizing}
/>
@@ -8,7 +8,7 @@
// its controls, macOS traffic lights included.
export const SESSION_PANEL_WIDTH_MIN = 400
const SIDE_PANE_WIDTH_MIN = 320
export const SIDE_PANE_WIDTH_MIN = 320
const SESSION_PANEL_WIDTH_FIT = 450
@@ -33,6 +33,11 @@ export function sessionPanelWidthCss(input: { width: number; split: boolean; res
return `max(${SESSION_PANEL_WIDTH_MIN}px, min(${input.width}px, max(${minimum}px, 100% - ${pane + 8}px)))`
}
// A panel with a side width of its own: the chat panel takes the rest of the row, keeping at least its minimum.
export function sidePanelWidthCss(side: number) {
return `max(${SESSION_PANEL_WIDTH_MIN}px, 100% - ${Math.max(SIDE_PANE_WIDTH_MIN, side) + 8}px)`
}
// `available` is undefined until the layout row is first measured; render the
// stored width untouched until then to avoid a first-frame snap.
export function clampSessionPanelWidth(input: {
+18
View File
@@ -155,6 +155,8 @@ export const layoutSchema = Persistence.struct({
tab: Schema.Literals(["changes", "all"]),
}),
session: Persistence.struct({ width: Schema.Finite }),
// The side region's width per panel (`${plugin}:${panel id}`) that sizes itself, app-wide.
panelWidths: Schema.optional(Persistence.record(Schema.Finite)),
mobileSidebar: Persistence.struct({ opened: Schema.Boolean }),
sessionTabs: Persistence.record(Persistence.fallback(sessionTabsSchema, () => ({ all: [] }))),
sessionView: Persistence.record(Persistence.fallback(sessionViewSchema, () => ({ scroll: {} }))),
@@ -492,6 +494,22 @@ export const { use: useLayout, provider: LayoutProvider } = createSimpleContext(
setStore("session", "width", width)
},
},
/** The side region's width while a panel that sizes itself shows, keyed `${plugin}:${panel id}`. */
panelWidth: {
get: (panel: string) => store.panelWidths?.[panel],
set(panel: string, width: number) {
// A plugin passes this width; a non-finite one would fail the stored layout's decode.
if (!Number.isFinite(width)) return
if (!store.panelWidths) {
setStore("panelWidths", { [panel]: width })
return
}
setStore("panelWidths", panel, width)
},
},
mobileSidebar: {
opened: createMemo(() => store.mobileSidebar?.opened ?? false),
hide() {
@@ -398,7 +398,7 @@ export function mountBrowserPane(input: PaneHost) {
state: () => "visible",
open() {},
close() {},
side: { opened: () => true, toggle() {}, menu: () => [] },
side: { opened: () => true, toggle() {}, menu: () => [], width: () => undefined, resize() {} },
},
links: { open() {} },
stores: {
@@ -534,9 +534,7 @@ export function mountBrowserPane(input: PaneHost) {
aria-label="Picked element scenario"
onChange={(event) => setStore("selection", event.currentTarget.value)}
>
<For each={["default", "long", "fallback", "low", "zoomed"]}>
{(value) => <option>{value}</option>}
</For>
<For each={["default", "long", "fallback", "low", "zoomed"]}>{(value) => <option>{value}</option>}</For>
</select>
<button onClick={() => setStore("history", { visits })}>Seed history</button>
<button onClick={() => emit(store.session, { type: "page", tabID: current().id, icon, zoom: store.zoom })}>
@@ -874,7 +872,7 @@ export function mountBrowserRegion(input: RegionHost) {
},
stored: (session) =>
strip(session.key).all.flatMap((key) => (key.startsWith(`${plugin}:`) ? [key.slice(plugin.length + 1)] : [])),
side: { opened: () => true, toggle() {}, menu: () => [] },
side: { opened: () => true, toggle() {}, menu: () => [], width: () => undefined, resize() {} },
sidebar: { opened: () => true },
scroll: { get: () => undefined, set() {} },
settings() {},
+20
View File
@@ -892,6 +892,26 @@ export interface Layout {
* ```
*/
menu(): readonly SessionPanelMenuItem[]
/**
* The side region width the user dragged to, or `resize` stored, while one of your panel's tabs shows; undefined
* when none is stored, as before the app interface mounts. Reactive.
*
* @param panel - Your `Panel`'s id.
*/
width(panel: string): number | undefined
/**
* Stores the side region width for your panel, as a drag on one of its tabs does; it applies while the side pane
* shows one of the panel's tabs, and the user's next drag replaces it. Waits until the app interface mounts.
*
* @param panel - Your `Panel`'s id.
* @param width - CSS pixels. The host keeps the conversation at its minimum width and the region at its own.
*
* @example
* ```ts
* ctx.layout.side.resize("quota", 360)
* ```
*/
resize(panel: string, width: number): void
}
/**
* The inner sidebar preference every side panel shares, which `usePanel().sidebar` also reads inside a panel render.
+10
View File
@@ -266,6 +266,16 @@ export interface Panel {
readonly region: "side"
/** Asks for the wider session minimum while the side region is open. Reactive. */
readonly wide?: boolean
/**
* Gives the panel a side region width of its own, for content that wants less room or more than other tabs. While the
* side pane shows one of the panel's tabs, the region takes the width the user last dragged it to on this panel,
* app-wide, else this one; other tabs keep the conversation's width. The host keeps the conversation at its minimum
* width and the region at least `narrow`. Omit it to share the conversation's width, unless `Layout.side.resize`
* stored one for the panel.
* - A number: CSS pixels.
* - `narrow`: the narrowest the region goes.
*/
readonly width?: number | "narrow"
/** Tabs are not restored: stored keys this panel stops listing leave the strip. See also `PanelTab.transient`. */
readonly transient?: boolean
/**
@@ -787,8 +787,31 @@ A panel's options:
- `mobile` adds a narrow-screen view of the panel. With `cached: true`, the view stays mounted while the user shows
another view. By default, the view mounts each time it shows.
- `wide` asks for the wider session minimum while the side region is open.
- `width` gives the panel a side region width of its own; see [Panel width](#panel-width).
- `transient` panels' tabs are not restored.
#### Panel width
By default, every tab in the side region shares the conversation's width. Set `width` when your panel needs less room
than a review or a browser, or more. Pass CSS pixels, or `"narrow"` for the narrowest the region goes.
```ts
ctx.add(Panel, {
id: "quota",
region: "side",
width: "narrow",
list: (input) => (input.open.includes("quota") ? [tab] : []),
render: () => <Quota />,
})
```
- The width applies while the side pane shows one of the panel's tabs. Other tabs keep the conversation's width.
- When the user drags the divider on one of the panel's tabs, the host keeps that width for the panel, app-wide, in place
of `width`.
- The host keeps the conversation at its minimum width and the region at least `"narrow"`.
- `ctx.layout.side.width(panel)` reads the stored width, and `ctx.layout.side.resize(panel, width)` stores one, as a drag
does. A stored width applies even to a panel without `width`.
A tab's options:
- `id` is the tab id; its host key is `<plugin id>:<id>`. `title` is its accessible name, and `label` renders custom
@@ -812,6 +835,7 @@ interface Panel {
region: "side"
mobile?: MobileView
wide?: boolean
width?: number | "narrow"
transient?: boolean
list(input: { session: MountedSession; screen: SessionScreen; open: string[] }): PanelTab[]
render(props: PanelProps): JSX.Element
@@ -1473,6 +1497,8 @@ if (session) ctx.layout.open(`${ctx.id}:main`, session, { tab: "select", backgro
- `ready()` is `true` once the stored layout has loaded, and `narrow()` while the viewport is under 768px.
- `side.opened(session)` is `true` while the side region is open, and `side.toggle(session)` opens or closes it.
- `side.menu()` lists every plugin's `session.panel` [menu items](#menu-items) in `order`, for a launcher of your own.
- `side.width(panel)` and `side.resize(panel, width)` read and store the side region width of one of your panels; see
[Panel width](#panel-width).
- `sidebar.opened()` is the inner sidebar preference that every side panel shares.
- `scroll` stores scroll offsets per session and key.
- `settings(page?)` opens Settings. `project(server, title)` opens a project's directory picker and a new draft.
@@ -1504,6 +1530,8 @@ interface Layout {
opened(session: SessionRef): boolean
toggle(session: SessionRef): void
menu(): SessionPanelMenuItem[]
width(panel: string): number | undefined
resize(panel: string, width: number): void
}
sidebar: {
opened(): boolean