Workspace

zidane-ui/workspace holds the desktop app's side panel: tab groups drawn side by side or stacked, a strip per group with its pills, the drag and drop that moves a tab between strips or splits a group, the dividers between groups and the panel's resizable edge. What each tab shows is yours. The panel reads a WorkspaceHost for where each scope's layout is kept and for extension panels. The previews below run on the fixture host. Pick a tab, drag one onto another strip or onto the edge of a body, or drag a divider.

Mount it#

Wrap the panel in a WorkspaceProvider with the scope on screen and the tabs you offer, and give SidePanel a registry that turns each tab into a React node.

import 'zidane-ui/styles.css'
import { SidePanel, WorkspaceProvider } from 'zidane-ui/workspace'

const TABS = [
  { id: 'files', label: 'Files', icon: { gui: 'i-ph-folder-simple' }, builtin: true },
  { id: 'notes', label: 'Notes', icon: { gui: 'i-ph-note' }, builtin: true },
]

const registry = {
  render: tab => (tab.id === 'files' ? <FilesTab /> : <NotesTab />),
  keepAlive: () => true,
}

export function Panel({ host, sessionId }) {
  return (
    <WorkspaceProvider host={host} scope={{ key: sessionId }} tabs={TABS}>
      <SidePanel registry={registry} width={480} minWidth={320} maxWidth={900} onWidthCommit={saveWidth} controls={{ onClose: close }} />
    </WorkspaceProvider>
  )
}

AppHostProvider (zidane-ui/app) puts host.workspace in context, so a WorkspaceProvider below it can leave host out.

Your tabs#

A tab is { id, label, icon?, builtin }. Your own kinds are builtin: true and render through the registry. builtin: false is an extension panel: its content loads from the host, and its pill shows the badge the content carries.

A body reads usePanelVisible() to pause work while it is hidden. Bodies are rendered once and parked into their group's slot, so a tab moved to another group keeps its state.

Pick a host#

On zidane-server, extension panels run on the server: panels.list, panels.load, panels.action, panels.watch while a panel is shown (watched again after a reconnect) and panels.unwatch once it is hidden, with panel:changed and catalog:changed for the updates.

What a host offers#

Every member is optional. Without layouts a layout lasts as long as the page. Without panels the strip shows only your tabs.

useWorkspaceView() reads the strips and the open state, useWorkspaceActions() the actions (pick, close, move, split, drop, resize, cycle, attention), and useWorkspaceContent() the extension content and badges. Each re-renders only for its own part.

Extension panel content#

An extension panel ships data, not markup: PanelContent (zidane/chat/pure), sections of rows, prose and key / value facts, plus footer actions. PanelContentView paints it in the Artifacts panel's vocabulary: a row is a glyph, a title, a subtitle, a status, chips (lead, diff, facts) and badges, and a row with details collapses to a two-line preview. Feed it contentFor(id) from useWorkspaceContent(). onAction runs a row's or a footer's action (act(id, actionId, payload)); onOpenPath opens a row whose href is a path, and without it such rows are not links. Keep both stable: the view is memoised.

SidePanel draws the panel's own buttons on its top-right strip when you pass controls. To draw them yourself over the band instead, leave controls out, render PanelCorner (the toggle, then pop out and full screen while the panel shows) at the top-right of the area, and pass endInset={`${panelCornerWidth(n)}px`} so the strip keeps room for it. expanded makes the panel cover its parent: the aside keeps its width in the row and only its clip opens, so the content beside it never reflows. startInset keeps room at the strip's start for window controls.

Content can also carry big-number stats, a heatmap, stacked bars, rows with a meter, rows that stand for a session (onOpenSession opens them) and segmented controls in its header: pass onControl to keep the picked option as the panel's view[id] and reload it, or the controls stay hidden. variant="block" paints the same content as a card body on the project home (ProjectHome, zidane-ui/session): as tall as its content, sections split by a line. Under a PanelSessionRowProvider row={YourRow}, a row that stands for a session is drawn with your component ({ item, session, fallback }): the desktop app gives its sidebar row, so the project home's Recent sessions block looks and moves like the session list. Draw fallback for a session you don't know.

function ExtensionTab({ id }: { id: string }) {
  const { contentFor } = useWorkspaceContent()
  const { act } = useWorkspaceActions()
  const entry = contentFor(id)
  const onAction = useCallback((actionId: string, payload?: unknown) => void act(id, actionId, payload), [act, id])
  return <PanelContentView content={entry.content} loading={entry.loading} error={entry.error} onAction={onAction} />
}

Keys and hand-overs#

The horizontal budget#

LayoutBudgetProvider fits the sidebar, the chat and the panel into the window. It keeps the chat at its floor by shrinking the panel, then the sidebar, then floating the panel over the chat, then collapsing the sidebar. Read the result with useLayoutBudget(). resolveLayout (zidane-ui/workspace/headless) is the same rule as a pure function.

Per-scope layout memory#

createLayoutMemory({ storage }) (zidane-ui/workspace/headless) remembers how each conversation's window was left: the panel's tree, width and share, the Files tab (open files, tree column, filters), the terminal drawer and tab order, and the composer badges' order. A new session copies its project's last-used layout once, then owns its own, so another session's change never moves it. storage is read on each access (() => localStorage); a write that fails keeps the layout for this window. Other windows' writes arrive as storage events.

Feed it the session → scope mapping (setSessionScopes), read a scope with useScopeLayout(memory, scope) (zidane-ui/workspace), change it with updateScopeLayout(scope, patch) (a function patch reads what is stored now), and call sweepScopeLayouts(listLocalSessions) once per launch to drop records nothing can show again. A scope is { root, cwd, session?, draft? }: layoutScopeKey and layoutProjectKey are its keys.

Test your host#

zidane-ui/workspace/testing/contract is the suite every host runs, in your own vitest. Build your host over a backend that holds the layouts and panels it is given, and list the members it offers.

import { describeWorkspaceHostContract } from 'zidane-ui/workspace/testing/contract'

describeWorkspaceHostContract('my host', backend => makeHarness(backend), ['layouts'])