Version 0.3 makes layouts and inner bars first-class tab content. Existing stored 0.1 and 0.2 layouts migrate on read, but callers must adopt the tree-and-zone APIs. Storage compatibility does not make old method calls valid.
0.2 → 0.3 mapping
This mapping is shared with the README's breaking-change reference:
| Before | 0.3 |
|---|---|
place, moveTo, split(id, orientation, pane), splitAt, insertSplit, and insert(id, pane, beforeId) |
Replaced by move(source, zone), canMove(source, zone), and insert(id, zone, register?); commands create placeholders. |
select(pane, id) where pane was a pane only |
select(tabSet, key) keeps selection semantics; a tab set can be any visible bar. |
intent.order, intent.firstActive, and intent.ratio |
Removed; intent is v3 { version, tree, focus, opened, titles? }. |
canOfferSplit and ratio controller members |
Removed; use effective fits, cuts, and explicit cut methods. |
defaultRatio option |
Removed; ratios live in the cut tree. Use commitRatio(ratio, cut) to resize a cut or equalize(cut) to balance it. |
dividerSize: 0 |
Values below 1 now throw at controller creation; choose a thickness of at least 1 px. |
PaneNode type export |
Replaced by TabSetNode; a tab set holds views, layouts, or other tab sets. |
Host-rendered SplitTabStrip inside #pane or #frame |
Remove it. SplitTabs renders all bars outside content; move labels, closeButton, alwaysShow, tabClass, iconClass and #tab to the root. |
Strip #end host controls |
Move to root #bar-end="{ tabSet }"; #bar-start provides the other end. Request alwaysShow for any set whose controls must remain visible. |
| Pane selectors included the bar | .split-tabs-tabset[data-tabset-id] is the whole box; .split-tabs-bar[data-bar-id] is its bar; .split-tabs-pane[data-pane-id] is content only. |
Standalone SplitTabStrip prop pane |
Renamed to tabSet; standalone use only, not inside root content slots. |
labels.rows / labels.cols and per-tab split buttons, splitButtons, --split-tabs-icon-size, --split-tabs-icon-hit-size |
Removed: split by dragging a tab, by the keymap, or by the tab context menu. |
startExternalDrag(event, id, ghost, labels, beforeDrop) |
startExternalDrag(event, id, ghost, beforeDrop). |
Old TabDropTarget |
Now carries a bar, inside, split, or bin target plus its checked result and preview geometry. |
.split-tab-strip-marker[data-before] and --split-tabs-marker-width |
Removed; style .split-tabs-drop-shade[data-marker] with --split-tabs-marker-color. Geometry sets its size. |
SplitSide |
Removed in favour of Side (union below). |
paneKey |
Replaced by tab-set injection; descendants use their containing tab set. |
| Centre pane drop moved to another pane | Centre drop creates an inner bar inside the zone. |
| One-tab bars shown when split | Hidden by default; use :always-show="controller.hasSplit.value" on SplitTabs to show bars when the unzoomed working tree is split, even if size-collapsed. |
Existing stored 0.1 and 0.2 data migrates when read, but TypeScript callers must move to the tree and zone APIs.
Side is 'top' | 'right' | 'bottom' | 'left'.
Migrate an integration in layers
- Keep your storage identity and host tab ids so the controller can read the existing table. Do not rewrite old entries by hand; use the reader's validation and migration path.
- Replace old placement/split calls with a source and zone. A move carries an existing view or node;
split(side)creates a placeholder and returns its id. These are deliberately different operations. - REMOVE strips from
#paneand#frame. The library renders bars beside content. Move strip labels to rootstripLabels,closeButton,alwaysShow,tabClassandiconClassto root props; move#tabto the root and#endto#bar-end { tabSet }(an effective tab-set object). Pane slots now render content/anchors only; frame slots add content before the recursive layout. UsealwaysShow=trueor a per-set function to keep an add control available on one-tab sets. - Remove per-tab split-button expectations. Supply a keymap, drag targets, and labelled context-menu actions instead.
- Verify middle drops as inside and bar drops as next-to. Existing UI hints that call both “move to pane” should explain the level instead.
- Test narrow containers and restore: persist
intent, not the effective collapsed presentation. Check focus marks over iframe content as well as ordinary panes.
Replace whole-box [data-pane-id] selectors with .split-tabs-tabset[data-tabset-id]. The pane attribute now identifies only content. Bars use .split-tabs-bar[data-bar-id] and retain strip hooks. Set barThickness for actual top/bottom bar height; the root writes --split-tabs-bar-thickness. Content opacity and marks exclude bars. Storage, algebra, Keep keys and frame-helper setup do not change.
Translate placement into a destination
// Move an existing view beside the currently focused pane.
controller.move(
{ view: 'preview' },
{ kind: 'split', target: controller.focus.value, side: 'right' },
);
// Add the view beside entries in a specific bar.
controller.move(
{ view: 'preview' },
{ kind: 'bar', target: destinationTabSet, index: null },
);
// Create a new space; the host supplies its eventual content.
const result = controller.split('bottom');
if (result.ok && result.view) {
tabs.value = [...tabs.value, 'outline'];
controller.replace(result.view, 'outline');
}The host defines destinationTabSet and the reactive tabs list here. Use canMove to show availability before offering an action and handle the actual move result too: a reactive host can change between preview and drop.
What the reader preserves
The 0.2 migration maps old pane leaves to tab sets, retains cuts and ratios, and uses saved order to place assigned and unassigned ids. In the controller specification, a stored columns tree with firstActive: "d" and order ["d", "c", "b", "a"] becomes H[(*d b) (c *a)], retaining ratio 0.3. An old two-pane rows entry with b in the second pane becomes V[(*a c d) b]. These are read migrations, not a requirement for hosts to manufacture v3 storage objects themselves.
Review The layout model for optional visibility and focus semantics, then use the complete controller declaration to update TypeScript callers. The Workbench makes the new nested levels and drop behavior observable before integrating them into an application.