Skip to main content

Workbench

Workbench combines the file tree, file tabs and the file editor around one adapter. It loads the tree, opens each selected file in a tab, tracks unsaved edits per tab, and saves through the adapter.

The demo uses an in-memory adapter, codeEditorRenderer with JSON and Markdown added, lucide icons, and the stylesheet in this site's src/css/demo.css. Try editing a file and pressing Ctrl+S (Cmd+S on macOS), turning on "Fail saves" and saving, dragging tabs, and dragging the separator.

import { Workbench } from '@jbpark/workbench';
import { codeEditorRenderer } from '@jbpark/workbench/code-editor';

<div style={{ height: 480 }}>
<Workbench adapter={adapter} renderEditor={codeEditorRenderer} />
</div>;

Props​

PropTypeMeaning
adapterWorkbenchAdapterData source. Replacing it reloads the tree and closes every tab. See Adapters
renderEditorWorkbenchEditorRendererEditor to render. See File editor
readOnlybooleanView files without editing. Defaults to false
renderIconFileTreeIconRendererTree and tab icons. See File tree
colorTheme'dark' | 'light'Color scheme. Defaults to 'dark'
onBeforeCloseTab(tab: { node: WorkbenchNode; content: string }) => boolean | Promise<boolean>Runs before a tab with unsaved edits closes. Return false to keep it open. See Behavior
defaultSidebarSizenumberInitial sidebar width in percent of the widget. Defaults to 20. See Behavior
minSidebarSizenumberNarrowest sidebar width in percent. Defaults to 15
maxSidebarSizenumberWidest sidebar width in percent. Defaults to 50
onSidebarResize(size: number) => voidCalled when a drag or key press that changed the sidebar width ends
renderLayout(props: WorkbenchLayoutProps) => ReactNodeArranges the tree and the editor instead of the built-in layout. See Custom layout

Behavior​

  • Saving. The save button saves the active tab and is enabled while it has unsaved edits. Cmd/Ctrl+S in the editor saves the editor's latest text through the same path. A save stays tied to its tab even if you switch tabs while it runs. A successful adapter.writeFile clears the unsaved state; a failed one keeps it and shows the error.

  • Errors. Failures from getTree, loadChildren, readFile and writeFile show the adapter's message in [data-workbench-error] with role="alert". The message is cleared when the next file is opened or saved.

  • Read-only. With readOnly, files still open, but the editor receives readOnly: true, no save button is rendered, edits and save shortcuts are ignored even from an editor that does not honor readOnly, and adapter.writeFile is never called. Use it for sources that cannot be written, such as createHttpAdapter.

  • Tabs. Each opened file gets a tab that keeps its own content and unsaved edits. Selecting a file that is already open activates its tab without reading it again. Closing the active tab activates the tab to its right, or to its left when it was last. Drag a tab onto another to move it there (native HTML drag and drop); a middle click closes it. Tab icons come from renderIcon, called with expanded: false.

  • Closing unsaved tabs. Closing a tab discards its unsaved edits unless onBeforeCloseTab stops it. Both the close button and a middle click call it for a dirty tab with the tab's file and current content; clean tabs close without it. Return false (or a promise of false) to keep the tab, or true to close it. The tab stays open while a returned promise is pending, and closing it again meanwhile does not call the callback a second time. A thrown error or rejection keeps the tab open and shows its message in [data-workbench-error]. Workbench ships no dialog, so ask with window.confirm, your own modal, or save first:

    <Workbench
    adapter={adapter}
    renderEditor={codeEditorRenderer}
    onBeforeCloseTab={({ node }) =>
    window.confirm(`Discard unsaved changes to ${node.name}?`)
    }
    />

    Replacing adapter still closes every tab without calling it.

  • Theme. colorTheme sets data-theme on the root and is passed to the editor renderer as theme, so the tree, tabs and editor switch together. Workbench defines no colors: write them under [data-theme='dark'] and [data-theme='light']. Changing the theme keeps open tabs and unsaved edits. The demo above follows this site's theme toggle.

  • Resizing. A separator between the tree and the editor resizes the sidebar. Drag it with a mouse, touch or pen, or focus it and use the arrow keys (1% per press), Home (narrowest) and End (widest). The sidebar starts at defaultSidebarSize (20% of the widget width) and stays between minSidebarSize (15%) and maxSidebarSize (50%); a default outside the limits starts at the nearest one. Its width is set inline, so consumer CSS should not set one. onSidebarResize receives the new width once per drag or key press that changed it, so a saved width can come back as defaultSidebarSize:

    <Workbench
    adapter={adapter}
    renderEditor={codeEditorRenderer}
    defaultSidebarSize={Number(localStorage.getItem('sidebar')) || undefined}
    onSidebarResize={size => localStorage.setItem('sidebar', String(size))}
    />

Layout​

Workbench ships no CSS. Give it a parent with a height, then lay out its regions through their attributes; the tree only renders with a bounded height. A minimal layout:

[data-workbench] {
display: flex;
height: 100%;
}
[data-workbench-resize-handle] {
width: 4px;
cursor: col-resize;
}
[data-workbench-main] {
display: flex;
flex: 1;
flex-direction: column;
min-width: 0;
}
[data-workbench-editor],
[data-workbench-content] {
flex: 1;
min-height: 0;
}

Styling lists every attribute and has a complete stylesheet.

Custom layout​

renderLayout replaces the built-in sidebar, separator and main arrangement, for example to stack the tree above the editor on a narrow screen or to use another split component. It receives:

FieldTypeMeaning
sidebarReactNodeThe tree in [data-workbench-sidebar]
mainReactNodeTabs, save button, error and editor in [data-workbench-main]
sidebarIdstringThe id of [data-workbench-sidebar], for a separator's aria-controls

Its result is rendered inside the [data-workbench] root, and every attribute inside the two regions stays the same, so the selectors in Styling keep working. Workbench then renders no separator, sets no sidebar width and ignores the sidebar size props; the layout sizes the regions.

const isNarrow = useMediaQuery('(max-width: 640px)');

<Workbench
adapter={adapter}
renderEditor={codeEditorRenderer}
readOnly
renderLayout={
isNarrow
? ({ sidebar, main }) => (
<div className="stacked">
{sidebar}
{main}
</div>
)
: undefined
}
/>;
.stacked {
display: flex;
flex-direction: column;
width: 100%;
}
.stacked [data-workbench-sidebar] {
height: 40%;
}
.stacked [data-workbench-main] {
flex: 1;
min-height: 0;
}

Switching between layouts mounts the regions again. Open tabs and unsaved edits are kept, but the tree's expanded folders and the editor's undo history start over.