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
| Prop | Type | Meaning |
|---|---|---|
adapter | WorkbenchAdapter | Data source. Replacing it reloads the tree and closes every tab. See Adapters |
renderEditor | WorkbenchEditorRenderer | Editor to render. See File editor |
readOnly | boolean | View files without editing. Defaults to false |
renderIcon | FileTreeIconRenderer | Tree 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 |
defaultSidebarSize | number | Initial sidebar width in percent of the widget. Defaults to 20. See Behavior |
minSidebarSize | number | Narrowest sidebar width in percent. Defaults to 15 |
maxSidebarSize | number | Widest sidebar width in percent. Defaults to 50 |
onSidebarResize | (size: number) => void | Called when a drag or key press that changed the sidebar width ends |
renderLayout | (props: WorkbenchLayoutProps) => ReactNode | Arranges 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.writeFileclears the unsaved state; a failed one keeps it and shows the error. -
Errors. Failures from
getTree,loadChildren,readFileandwriteFileshow the adapter's message in[data-workbench-error]withrole="alert". The message is cleared when the next file is opened or saved. -
Read-only. With
readOnly, files still open, but the editor receivesreadOnly: true, no save button is rendered, edits and save shortcuts are ignored even from an editor that does not honorreadOnly, andadapter.writeFileis never called. Use it for sources that cannot be written, such ascreateHttpAdapter. -
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 withexpanded: false. -
Closing unsaved tabs. Closing a tab discards its unsaved edits unless
onBeforeCloseTabstops 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. Returnfalse(or a promise offalse) to keep the tab, ortrueto 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 withwindow.confirm, your own modal, or save first:<Workbenchadapter={adapter}renderEditor={codeEditorRenderer}onBeforeCloseTab={({ node }) =>window.confirm(`Discard unsaved changes to ${node.name}?`)}/>Replacing
adapterstill closes every tab without calling it. -
Theme.
colorThemesetsdata-themeon the root and is passed to the editor renderer astheme, 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 betweenminSidebarSize(15%) andmaxSidebarSize(50%); a default outside the limits starts at the nearest one. Its width is set inline, so consumer CSS should not set one.onSidebarResizereceives the new width once per drag or key press that changed it, so a saved width can come back asdefaultSidebarSize:<Workbenchadapter={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:
| Field | Type | Meaning |
|---|---|---|
sidebar | ReactNode | The tree in [data-workbench-sidebar] |
main | ReactNode | Tabs, save button, error and editor in [data-workbench-main] |
sidebarId | string | The 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.