# PanelLayout An IDE-style tiling workspace. Panels split, resize, drag onto each other's edges to re-dock, and merge into tab groups — all over a recursive tree the host can read, write, and persist. It is **view-agnostic by construction**. A panel carries a `view` string that only your `renderBody` / `renderHeader` interpret; the layout never reads it. Everything a real app needs on top — which views may be tabbed, which one reclaims space when a panel closes, which panels stay transparent — is injected through props rather than inferred. Three layers ship separately, and the lower two are useful on their own: | Layer | What it is | | ------------- | ------------------------------------------------------------------- | | `panel-tree` | The pure tree — nodes, migration, mutators. No React, no DOM. | | `panel-box` | Panel geometry as CSS math, published as `--panel-x` / `--panel-w`. | | `PanelLayout` | The renderer plus the pointer and keyboard wiring. | ## Declarative requests and agent control Use the [layout controller](/components/layout-controller.md) to address named destinations, select panels by geometry or content, and apply pin-aware spawn requests. It provides inspect → resolve → apply above these low-level mechanics, with forkable examples. ## Demo Drag a divider to resize. Grab the **handle at the top of a panel header** and drop it on another panel: near an edge it docks to that side, in the centre it merges as a tab. `⌘D` splits the focused panel to the right, `⌘⇧D` below. Escape cancels a drag in flight. > **Note:** `PanelLayout` fills its container. Without an ancestor that has a real height it collapses to > nothing — the demos here sit in a fixed-height box. ## Tab groups A `group` is a flat tab bar of panels sharing one region. By default, only the active tab is mounted. Enable `tabbed` to keep each view mounted and connected while switching tabs or docking it into another region. Groups normally arise from a user dropping one panel onto another's centre, so `panelGroup` is how you seed a layout that already has tabs. A tab can be dragged straight out of its group to dock elsewhere, and a group that loses its second-to-last tab collapses back into a plain panel. ## Persistent editor and preview views Use `tabbed` for editors, collaborative documents, and iframe previews that must retain their own state when hidden or moved. Each leaf keeps one connected body; inactive bodies are hidden. Closing a leaf disposes its body. A singleton uses the same header row without an extra tab strip. Multiple views show tabs beside the active view's header controls. Custom labels stay on one line and clip when they reach those controls. ```tsx panelGroup([panelLeaf({ view: 'editor', title: 'Draft' }), panelLeaf({ view: 'preview', title: 'Preview' })])} renderTab={(leaf) => {leaf.title}} renderHeader={(leaf) => } renderBody={(leaf) => } onFocusedLeafChange={(leaf) => setActiveView(leaf.id)} onRequestClose={(id) => { if (canClose(id)) layout.current?.closeLeaf(id) }} /> ``` `onRequestClose` delegates user close actions to the host. When supplied, the host must call `closeLeaf` after its save/discard guard permits disposal. `showSingleTab` can opt individual singleton leaves into tab presentation. Calling `focusLeaf(id)` also activates that leaf when it belongs to a group. Keep resource identity keyed by leaf ID; hiding or moving a view must not replace its document or authorization context. ## Singletons Some views should never be tabbed — a settings pane, a connection status, a sessions list you want exactly one of. `isTabbable` marks them: the centre drop zone is suppressed whenever either side of a merge is a singleton, so the live drag preview and the actual drop always resolve to the same edge. Drag **Settings** onto the editor's centre below — it docks to an edge instead of merging. Drag Editor and Terminal onto each other and they tab. ## Panels that stay A panel can be the SUBJECT of a screen rather than an auxiliary view — the note you are reading, with reference panels beside it. Closing that one would leave a window of satellites with nothing to orbit. `closable` refuses it. The header's close button goes, a tab's × goes, and Delete on that tab does nothing. It is a policy rather than a class hook precisely because hiding the button is not enough: Delete never touches one, so the refusal lives next to the close handler and the affordances just reflect it. ```tsx leaf.view !== 'subject'} primaryView="subject" /> ``` The imperative `closeLeaf` is deliberately NOT gated — a host taking a panel away itself already knows its own policy, and would otherwise have to flip the predicate first just to clean up after a route change. ## Filling the panels `renderBody` and `renderHeader` are the only place a `view` string means anything. A custom header replaces the default dot-and-title, but the drag handle and close button stay — they are chrome the layout always owns. `primaryView` names the panel that reclaims space: close `Terminal` below and `Editor` absorbs the whole freed slot instead of every sibling growing a little. ## Driving it from code The ref handle mutates the same tree the user does, and `onChange` reports every mutation from either source. ## Persisting a layout Save on `onChange`, restore in `initial`. `usePersistedPanelLayout` is both halves, with the parts that are easy to get wrong already handled. ```tsx const persisted = usePersistedPanelLayout({ key: 'my-app:layout', fallback: () => panelSplit('row', [panelLeaf({ view: 'chat' }), panelLeaf({ view: 'files' })]), validate: (root) => hasView(root, 'chat'), // reject a saved tree missing the primary panel }) ``` > **Warning:** Saved layouts are wrapped in a `{ v, root }` envelope, which has no top-level > `kind`. Shape-check the raw blob first and you reject every layout saved under > the current format — silently wiping the user's layout on upgrade. > `unwrapLayout` handles both the envelope and a bare tree from before it > existed; `normalizeTree` migrates whatever comes out. | Option | Type | Default | Description | | ------------ | ----------------------------- | -------------- | ---------------------------------------------------- | | `key` | `string` | — | Storage key. Namespace it per user or workspace. | | `fallback` | `() => PanelNode` | — | Tree to use when nothing usable is saved. | | `storage` | `Storage` | `localStorage` | Any `Storage` — e.g. `sessionStorage`. | | `validate` | `(root) => boolean` | — | Last word on a restored tree, run _after_ migration. | | `transform` | `(root) => PanelNode \| null` | — | Narrow what gets saved — pair with `scopeSubtree`. | | `debounceMs` | `number` | `150` | Write coalescing window. `0` writes immediately. | Returns `{ initial, onChange, clear, reset }`. A pending write is flushed on unmount and on `pagehide`, so the last drag of a session isn't lost. > **Warning:** `initial` RESTORES a layout, so wiring the toolbar's Reset to it hands back the very layout the > user is clearing. `reset()` is the other half — it forgets the saved layout and returns the > fallback. Pass it as `resetTo`, or call it yourself and give the result to `replaceRoot`. ## Scoped layouts "The layout is per-document and swaps when you switch documents" falls apart the moment app-wide chrome shares the same tree: a connection panel or a settings pane either duplicates into every document's saved layout, or vanishes when you open a document whose layout predates it. Give each panel an owner. `scopeSubtree` then extracts just the part one owner is responsible for, and `tagOwnerScopes` stamps the scope into the tree before you save it — so a later reader honours what was saved rather than re-deriving it from a rule that has since changed. ```tsx const scopeOf = (leaf) => (GLOBAL_VIEWS.has(leaf.view) ? 'global' : 'document') usePersistedPanelLayout({ key: `doc:${docId}:layout`, fallback: freshDocLayout, transform: (root) => scopeSubtree(root, 'document', scopeOf), }) ``` `pruneLeaves(node, keep)` is the primitive underneath, and is useful on its own whenever you need to drop panels and be left with a tree that still renders: a split keeps the sizes of its survivors (renormalized), a split down to one child is replaced by that child, and a group collapses by the group's rules — a stale active tab is re-clamped rather than left dangling. ## Opening a view `resolveViewSplit` answers "where should this view open?" with no DOM and no side effects, so the decision is testable on its own. It returns `{ skip: true }` when the view is already open, which is what makes an open IDEMPOTENT — a deferred open that re-runs after the panel exists is a no-op rather than a second copy. ```tsx const plan = resolveViewSplit({ root: panelRef.current?.getRoot() ?? null, view: 'diff', anchorView: 'editor', // open alongside the primary panel fallbackLeafId: firstLeafId, prefs, // remembered { dir, before, px } per view widthOf: (id) => measure(id), }) if (!('skip' in plan)) { panelRef.current?.splitWith(plan.targetId, plan.dir, 'diff', 'Diff', plan.before, plan.fraction) } ``` A remembered pixel width is converted to a fraction of the target's _current_ width, so a restored width behaves at any window size; an unmeasurable target drops the fraction instead of dividing by zero. ## Keyboard and accessibility | Where | Keys | | -------------- | ------------------------------------------------------------------------------------------------- | | Any panel | `⌘/Ctrl D` split right · `⌘/Ctrl ⇧D` split down (see `splitShortcut`) | | Tab bar | `←` `→` move between tabs (selection follows focus) · `Home` `End` first/last · `Delete` close | | Divider | `←` `→` (or `↑` `↓`) nudge · `PageUp` `PageDown` coarse · `Home` `End` to the minimum either side | | Drag in flight | `Escape` cancels | The tab bar is a real `tablist`: tabs are `