dockview-react 8.6.0 → 8.6.2

package/dist/dockview-react.js

@@ -1,6 +1,6 @@
 /**
  * dockview-react
- * @version 8.6.0
+ * @version 8.6.2
  * @link https://github.com/dockview/dockview
  * @license MIT
  */
@@ -51,7 +51,7 @@ react_dom = __toESM(react_dom);
 //#region ../dockview-core/dist/package/main.esm.mjs
 /**
 	* dockview-core
-	* @version 8.6.0
+	* @version 8.6.2
 	* @link https://github.com/dockview/dockview
 	* @license MIT
 	*/
@@ -725,7 +725,7 @@ react_dom = __toESM(react_dom);
 			resizeTimeout = setTimeout(() => {
 				cb();
 			}, DEBOUCE_DELAY);
-		}));
+		}), Disposable.from(() => clearTimeout(resizeTimeout)));
 	}
 	function shiftAbsoluteElementIntoView(element, root, options) {
 		var _options$buffer;
@@ -2259,12 +2259,20 @@ react_dom = __toESM(react_dom);
 		if (candiateNode instanceof BranchNode) return findLeaf(candiateNode.children[last ? candiateNode.children.length - 1 : 0], last);
 		throw new Error("invalid node");
 	}
+	/**
+	* The sizing to re-add a branch's child with, so a hidden child stays hidden
+	* (with its cached size) instead of coming back visible at size 0.
+	*/
+	function childSizing(node, index, size, scale = 1) {
+		const cachedVisibleSize = node.getChildCachedVisibleSize(index);
+		return cachedVisibleSize === void 0 ? size : Sizing.Invisible(Math.round(cachedVisibleSize * scale));
+	}
 	function cloneNode(node, size, orthogonalSize) {
 		if (node instanceof BranchNode) {
 			const result = new BranchNode(node.orientation, node.proportionalLayout, node.styles, size, orthogonalSize, node.disabled, node.margin);
 			for (let i = node.children.length - 1; i >= 0; i--) {
 				const child = node.children[i];
-				result.addChild(cloneNode(child, child.size, child.orthogonalSize), child.size, 0, true);
+				result.addChild(cloneNode(child, child.size, child.orthogonalSize), childSizing(node, i, child.size), 0, true);
 			}
 			return result;
 		} else return new LeafNode(node.view, node.orientation, orthogonalSize);
@@ -2273,13 +2281,14 @@ react_dom = __toESM(react_dom);
 		if (node instanceof BranchNode) {
 			const result = new BranchNode(orthogonal(node.orientation), node.proportionalLayout, node.styles, size, orthogonalSize, node.disabled, node.margin);
 			let totalSize = 0;
+			const cachedSizeScale = node.size === 0 ? 1 : size / node.size;
 			for (let i = node.children.length - 1; i >= 0; i--) {
 				const child = node.children[i];
 				const childSize = child instanceof BranchNode ? child.orthogonalSize : child.size;
 				let newSize = node.size === 0 ? 0 : Math.round(size * childSize / node.size);
 				totalSize += newSize;
 				if (i === 0) newSize += size - totalSize;
-				result.addChild(flipNode(child, orthogonalSize, newSize), newSize, 0, true);
+				result.addChild(flipNode(child, orthogonalSize, newSize), childSizing(node, i, newSize, cachedSizeScale), 0, true);
 			}
 			return result;
 		} else return new LeafNode(node.view, orthogonal(node.orientation), orthogonalSize);
@@ -2765,7 +2774,8 @@ react_dom = __toESM(react_dom);
 				sizes.splice(parentIndex, 1, ...sibling.children.map((c) => c.size));
 				for (let i = 0; i < sibling.children.length; i++) {
 					const child = sibling.children[i];
-					grandParent.addChild(child, child.size, parentIndex + i);
+					const childSize = childSizing(sibling, i, child.size);
+					grandParent.addChild(child, !isSiblingVisible && typeof childSize === "number" ? Sizing.Invisible(childSize) : childSize, parentIndex + i);
 				}
 				/**
 				* clean down the branch node since we need to dipose of it and
@@ -3943,6 +3953,33 @@ react_dom = __toESM(react_dom);
 			return this.component.withOrigin("api", () => this.component.addGroup(options));
 		}
 		/**
+		* Serialize one group together with the state of every panel it holds.
+		* The result is self-contained and can be rehydrated with
+		* `addGroupFromJSON`, on this instance or another one.
+		*/
+		serializeGroup(group) {
+			return this.component.serializeGroup(group);
+		}
+		/**
+		* Rebuild a group from `serializeGroup` output and add it to the live
+		* layout, positioned as for `addGroup`, leaving the rest of the layout
+		* untouched. Throws before changing anything if a panel id is already in
+		* use.
+		*/
+		addGroupFromJSON(data, options) {
+			return this.component.withOrigin("api", () => this.component.addGroupFromJSON(data, options));
+		}
+		/**
+		* Add a panel from its `toJSON()` state, placed as `addPanel` places
+		* one: the counterpart to `panel.toJSON()` for a single tab moving
+		* between layouts or instances, as `addGroupFromJSON` is to
+		* `serializeGroup`. Throws before changing anything if the panel id is
+		* already in use.
+		*/
+		addPanelFromJSON(state, options) {
+			return this.component.withOrigin("api", () => this.component.addPanelFromJSON(state, options));
+		}
+		/**
 		* Close all groups and panels.
 		*/
 		closeAllGroups() {
@@ -5937,6 +5974,9 @@ react_dom = __toESM(react_dom);
 		get element() {
 			return this._element;
 		}
+		get dimensions() {
+			return this._dimensions;
+		}
 		constructor(accessor, group) {
 			var _this$accessor$resolv, _this$accessor, _this$accessor$resolv2, _this$accessor2, _this$accessor$onDidO, _this$accessor$onDidO2, _this$accessor3;
 			super();
@@ -5947,12 +5987,14 @@ react_dom = __toESM(react_dom);
 			this.onDidFocus = this._onDidFocus.event;
 			this._onDidBlur = new Emitter();
 			this.onDidBlur = this._onDidBlur.event;
+			this._onDidDimensionsChange = new Emitter();
+			this.onDidDimensionsChange = this._onDidDimensionsChange.event;
 			this._element = document.createElement("div");
 			this._element.className = "dv-content-container";
 			this._element.tabIndex = -1;
 			this._element.id = nextContentId();
 			this._element.setAttribute("role", "tabpanel");
-			this.addDisposables(this._onDidFocus, this._onDidBlur);
+			this.addDisposables(this._onDidFocus, this._onDidBlur, this._onDidDimensionsChange);
 			const getOverrideTarget = () => {
 				var _group$dropTargetCont;
 				return (_group$dropTargetCont = group.dropTargetContainer) === null || _group$dropTargetCont === void 0 ? void 0 : _group$dropTargetCont.model;
@@ -6061,7 +6103,15 @@ react_dom = __toESM(react_dom);
 			if (this.panel === panel) return;
 			this.renderPanel(panel);
 		}
-		layout(_width, _height) {}
+		layout(width, height) {
+			var _this$_dimensions;
+			if (((_this$_dimensions = this._dimensions) === null || _this$_dimensions === void 0 ? void 0 : _this$_dimensions.width) === width && this._dimensions.height === height) return;
+			this._dimensions = {
+				width,
+				height
+			};
+			this._onDidDimensionsChange.fire(this._dimensions);
+		}
 		closePanel() {
 			if (this.panel) {
 				if (this.panel.api.renderer === "onlyWhenVisible") {
@@ -6910,6 +6960,7 @@ react_dom = __toESM(react_dom);
 			className: void 0,
 			noPanelsOverlay: void 0,
 			closeEmptyGroups: void 0,
+			groupIdGenerator: void 0,
 			dndEdges: void 0,
 			dropPositionResolver: void 0,
 			dndCompass: void 0,
@@ -10438,6 +10489,15 @@ react_dom = __toESM(react_dom);
 		get panel() {
 			return this.options.panel;
 		}
+		/**
+		* For a drop on a group's tab bar, the tab index the drop landed at:
+		* where a panel added in response belongs (`addPanel`'s `index`, or
+		* `addGroupFromJSON` with `direction: 'within'`). `undefined` for a
+		* drop on a group's content or a layout edge.
+		*/
+		get index() {
+			return this.options.index;
+		}
 		get group() {
 			return this.options.group;
 		}
@@ -10526,7 +10586,6 @@ react_dom = __toESM(react_dom);
 			return (_this$_headerPosition = this._headerPosition) !== null && _this$_headerPosition !== void 0 ? _this$_headerPosition : "top";
 		}
 		set headerPosition(value) {
-			var _this$_activePanel;
 			this._headerPosition = value;
 			this.invalidateHeaderSize();
 			removeClasses(this.container, "dv-groupview-header-top", "dv-groupview-header-bottom", "dv-groupview-header-left", "dv-groupview-header-right");
@@ -10536,10 +10595,7 @@ react_dom = __toESM(react_dom);
 			this._headerDirection = direction;
 			this.tabsContainer.direction = direction;
 			this.header.direction = direction;
-			if ((_this$_activePanel = this._activePanel) === null || _this$_activePanel === void 0 ? void 0 : _this$_activePanel.layout) {
-				const { width, height } = this.contentDimensions();
-				this._activePanel.layout(width, height);
-			}
+			if (this.panels.length > 0) this.layoutContent();
 			this.updateHeaderActions();
 			if (previousDirection !== void 0 && previousDirection !== direction) {
 				var _this$groupPanel;
@@ -11042,10 +11098,7 @@ react_dom = __toESM(react_dom);
 			this.panels.forEach((panel) => {
 				this.rerender(panel);
 			});
-			if (this._activePanel) {
-				const { width, height } = this.contentDimensions();
-				this._activePanel.layout(width, height);
-			}
+			if (this.panels.length > 0) this.layoutContent();
 		}
 		get renderContainer() {
 			var _this$_overwriteRende;
@@ -11092,10 +11145,10 @@ react_dom = __toESM(react_dom);
 			return this.tabsContainer.indexOf(panel.id);
 		}
 		toJSON() {
-			var _this$_activePanel2;
+			var _this$_activePanel;
 			const result = {
 				views: this.tabsContainer.panels,
-				activeView: (_this$_activePanel2 = this._activePanel) === null || _this$_activePanel2 === void 0 ? void 0 : _this$_activePanel2.id,
+				activeView: (_this$_activePanel = this._activePanel) === null || _this$_activePanel === void 0 ? void 0 : _this$_activePanel.id,
 				id: this.id
 			};
 			if (this.locked !== false) result.locked = this.locked;
@@ -11133,8 +11186,8 @@ react_dom = __toESM(react_dom);
 		init(_params) {}
 		update(_params) {}
 		focus() {
-			var _this$_activePanel3;
-			(_this$_activePanel3 = this._activePanel) === null || _this$_activePanel3 === void 0 || _this$_activePanel3.focus();
+			var _this$_activePanel2;
+			(_this$_activePanel2 = this._activePanel) === null || _this$_activePanel2 === void 0 || _this$_activePanel2.focus();
 		}
 		openPanel(panel, options = {}) {
 			if (typeof options.index !== "number" || options.index > this.panels.length) options.index = this.panels.length;
@@ -11192,12 +11245,24 @@ react_dom = __toESM(react_dom);
 			this.updateContainer();
 		}
 		layout(width, height) {
-			var _this$_activePanel4;
 			this._width = width;
 			this._height = height;
-			const { width: contentWidth, height: contentHeight } = this.contentDimensions();
-			this.contentContainer.layout(contentWidth, contentHeight);
-			if ((_this$_activePanel4 = this._activePanel) === null || _this$_activePanel4 === void 0 ? void 0 : _this$_activePanel4.layout) this._activePanel.layout(contentWidth, contentHeight);
+			this.layoutContent();
+		}
+		/**
+		* Apply the current content box (group box minus header extent) to the
+		* content container and the active panel. Every path that can change that
+		* box goes through here so the container's recorded dimensions, which size
+		* overlay-rendered panels, never lag the active panel's. Callers other
+		* than `layout()` skip it for a group with no panels: there is nothing to
+		* size, and measuring the header of a group that is not in the document
+		* yet (the constructor sets `headerPosition`) would cache a zero extent.
+		*/
+		layoutContent() {
+			var _this$_activePanel3;
+			const { width, height } = this.contentDimensions();
+			this.contentContainer.layout(width, height);
+			if ((_this$_activePanel3 = this._activePanel) === null || _this$_activePanel3 === void 0 ? void 0 : _this$_activePanel3.layout) this._activePanel.layout(width, height);
 		}
 		/**
 		* Re-run the group's layout with its current dimensions. Used to propagate a
@@ -11290,8 +11355,7 @@ react_dom = __toESM(react_dom);
 				this.tabsContainer.setActivePanel(panel);
 				this.contentContainer.setLabelledBy(this.tabsContainer.getTabId(panel.id));
 				this.contentContainer.openPanel(panel);
-				const { width, height } = this.contentDimensions();
-				panel.layout(width, height);
+				this.layoutContent();
 				this.updateMru(panel);
 				this.contentContainer.refreshFocusState();
 				this._onDidActivePanelChange.fire({
@@ -11303,8 +11367,8 @@ react_dom = __toESM(react_dom);
 		}
 		/** Label the group region with its active panel's title (the WAI-ARIA region name). */
 		updateAccessibleLabel() {
-			var _this$_activePanel5;
-			const title = (_this$_activePanel5 = this._activePanel) === null || _this$_activePanel5 === void 0 ? void 0 : _this$_activePanel5.title;
+			var _this$_activePanel4;
+			const title = (_this$_activePanel4 = this._activePanel) === null || _this$_activePanel4 === void 0 ? void 0 : _this$_activePanel4.title;
 			if (title) this.container.setAttribute("aria-label", title);
 			else this.container.removeAttribute("aria-label");
 		}
@@ -11369,6 +11433,7 @@ react_dom = __toESM(react_dom);
 				nativeEvent: event,
 				position,
 				panel,
+				index,
 				getData: () => getPanelData(),
 				kind: getKind(),
 				group: this.groupPanel,
@@ -11414,6 +11479,7 @@ react_dom = __toESM(react_dom);
 				nativeEvent: event,
 				position,
 				panel,
+				index,
 				getData: () => getPanelData(),
 				group: this.groupPanel,
 				api: this._api
@@ -14350,6 +14416,15 @@ react_dom = __toESM(react_dom);
 		element.tabIndex = -1;
 		return element;
 	}
+	/**
+	* Write an inline pixel length only when it differs from what is already set,
+	* so a pass that re-derives geometry already in place leaves the element's
+	* style clean and the next measurement does not relayout the overlay subtree.
+	*/
+	function setPixels(style, property, value) {
+		const next = `${value}px`;
+		if (style[property] !== next) style[property] = next;
+	}
 	var OverlayRenderContainer = class extends CompositeDisposable {
 		constructor(element, accessor) {
 			super();
@@ -14468,6 +14543,32 @@ react_dom = __toESM(react_dom);
 			const generation = mapEntry.generation;
 			const focusContainer = mapEntry.element;
 			const contentElement = panel.view.content.element;
+			/**
+			* Size the overlay from the layout engine's numbers (the content box
+			* the group model also hands to `panel.layout()`): a style write with
+			* no forced layout, so the content has its real box before anything
+			* can measure it, and `.dv-render-overlay`'s 100%/100% default is never
+			* observed. Hidden panels are sized too: their content is laid out
+			* (hidden by `visibility`) and must not keep the root's box.
+			*
+			* Only while the overlay is not on screen at a measured position,
+			* i.e. hidden or not yet positioned. Once it is, the frame pass owns
+			* the whole box: size and position must change together, and group
+			* layouts driven from an animation frame would otherwise paint one
+			* frame at the new size and the old position. Likewise not while the
+			* peek force-shows the overlay, whose geometry belongs to
+			* `repositionPanelOverlay`: the collapsed group's own layouts describe
+			* the strip, not the peek. A zero box (a container awaiting layout) is
+			* skipped too: whether 0x0 is a real collapse is the frame pass's call.
+			*/
+			const applySize = (size) => {
+				if (!size || size.width <= 0 || size.height <= 0) return;
+				const entry = this.map[panel.api.id];
+				if (!entry || entry.forceVisible || entry.positioned && panel.api.isVisible) return;
+				setPixels(focusContainer.style, "width", size.width);
+				setPixels(focusContainer.style, "height", size.height);
+			};
+			applySize(referenceContainer.dimensions);
 			if (contentElement.parentElement !== focusContainer) focusContainer.appendChild(contentElement);
 			if (focusContainer.parentElement !== this.element) this.element.appendChild(focusContainer);
 			const resize = () => {
@@ -14507,10 +14608,10 @@ react_dom = __toESM(react_dom);
 					}
 					entry.retainPreviousGeometry = false;
 					entry.positioned = true;
-					focusContainer.style.left = `${left}px`;
-					focusContainer.style.top = `${top}px`;
-					focusContainer.style.width = `${width}px`;
-					focusContainer.style.height = `${height}px`;
+					setPixels(focusContainer.style, "left", left);
+					setPixels(focusContainer.style, "top", top);
+					setPixels(focusContainer.style, "width", width);
+					setPixels(focusContainer.style, "height", height);
 					if (panel.api.isVisible || forceVisible) {
 						focusContainer.style.visibility = "";
 						focusContainer.style.pointerEvents = "";
@@ -14626,6 +14727,9 @@ react_dom = __toESM(react_dom);
 					if (!panel.api.isVisible) return;
 					resize();
 				}),
+				referenceContainer.onDidDimensionsChange((size) => {
+					applySize(size);
+				}),
 				panel.api.onDidLocationChange(() => {
 					correctLayerPosition();
 				})
@@ -15591,6 +15695,8 @@ react_dom = __toESM(react_dom);
 	/** A never-firing history-change event, the fallback `onDidChangeHistory`
 	*  returns when the LayoutHistory module is absent. */
 	const NO_LAYOUT_HISTORY_CHANGES = NO_EVENT;
+	/** How many live ids a custom `groupIdGenerator` may return before giving up. */
+	const MAX_GROUP_ID_ATTEMPTS = 100;
 	var DockviewComponent = class extends BaseGrid {
 		fireDidCreateTabGroup(event) {
 			this._onDidCreateTabGroup.fire(event);
@@ -17440,7 +17546,7 @@ react_dom = __toESM(react_dom);
 					if (typeof id !== "string") throw new TypeError("dockview: group id must be of type string");
 					const group = this.createGroup({
 						id,
-						locked: !!locked,
+						locked: locked !== null && locked !== void 0 ? locked : false,
 						hideHeader: !!hideHeader,
 						headerPosition
 					});
@@ -17713,6 +17819,32 @@ react_dom = __toESM(react_dom);
 		addPanel(options) {
 			return this.mutation("add", () => this._doAddPanel(options));
 		}
+		/**
+		* Add a panel from its `toJSON()` state, placed as `addPanel` places
+		* one: the counterpart to `panel.toJSON()` for a single tab moving
+		* between layouts or instances, as `addGroupFromJSON` is to
+		* `serializeGroup`. Throws before changing anything if the panel id is
+		* already in use.
+		*/
+		addPanelFromJSON(state, options) {
+			if (!state.contentComponent) throw new Error(`dockview: serialized panel ${state.id} has no contentComponent`);
+			return this.mutation("add", () => {
+				const panel = this._doAddPanel(_objectSpread2$1(_objectSpread2$1({}, options), {}, {
+					id: state.id,
+					component: state.contentComponent,
+					tabComponent: state.tabComponent,
+					title: state.title,
+					renderer: state.renderer,
+					params: state.params,
+					minimumWidth: state.minimumWidth,
+					minimumHeight: state.minimumHeight,
+					maximumWidth: state.maximumWidth,
+					maximumHeight: state.maximumHeight
+				}));
+				if (state.pinned) this.setPanelPinned(panel, true);
+				return panel;
+			});
+		}
 		_doAddPanel(options) {
 			if (this.panels.some((_) => _.id === options.id)) throw new Error(`dockview: panel with id ${options.id} already exists`);
 			let referenceGroup;
@@ -17854,6 +17986,152 @@ react_dom = __toESM(react_dom);
 		addGroup(options) {
 			return this.mutation("add", () => this._doAddGroup(options));
 		}
+		/**
+		* Serialize one group and the state of every panel it holds. The result
+		* is self-contained: `addGroupFromJSON` on any dockview instance rebuilds
+		* the group from it, with the same tab order, active tab, panel titles,
+		* parameters and renderers.
+		*/
+		serializeGroup(group) {
+			const panels = {};
+			for (const panel of group.panels) panels[panel.id] = panel.toJSON();
+			return {
+				group: group.model.toJSON(),
+				panels
+			};
+		}
+		/**
+		* Rebuild a group from `serializeGroup` output and add it to the live
+		* layout at `options` (as for `addGroup`), without touching the rest of
+		* the layout. This is the counterpart to `fromJSON`, which replaces the
+		* whole layout, for moving one group between layouts or instances.
+		*
+		* With `direction: 'within'` and a reference group or panel, no group is
+		* created: the serialized panels are merged into that group, in their
+		* order, at `index` if given, and the serialized active panel becomes
+		* the group's. The serialized group's own shape (id, locked, header,
+		* tab groups) does not apply then. This is what a drop on a group's
+		* centre or tab bar calls for, and the only form that works against a
+		* floating or edge group, which has no grid neighbours.
+		*
+		* A panel id that is already live throws, as `addPanel` does, before
+		* anything is changed. A group id that is already live is reassigned with
+		* a warning, as `addGroup` does.
+		*/
+		addGroupFromJSON(data, options) {
+			this.validateSerializedGroup(data);
+			return this.mutation("add", () => this._doAddGroupFromJSON(data, options));
+		}
+		/**
+		* Refuse an envelope that cannot be applied cleanly, before any mutation
+		* is opened, so a refused call leaves no trace in the layout or its
+		* events.
+		*/
+		validateSerializedGroup(data) {
+			const state = data === null || data === void 0 ? void 0 : data.group;
+			if (typeof (state === null || state === void 0 ? void 0 : state.id) !== "string") throw new TypeError("dockview: group id must be of type string");
+			if (!Array.isArray(state.views)) throw new TypeError(`dockview: serialized group ${state.id} has no views`);
+			for (const id of state.views) {
+				var _data$panels;
+				if (!((_data$panels = data.panels) === null || _data$panels === void 0 ? void 0 : _data$panels[id])) throw new Error(`dockview: serialized group ${state.id} is missing panel state for ${id}`);
+				if (this.panels.some((panel) => panel.id === id)) throw new Error(`dockview: panel with id ${id} already exists`);
+			}
+		}
+		_doAddGroupFromJSON(data, options) {
+			var _options$direction;
+			const { id, locked, hideHeader, headerPosition, constraints, activeView, tabGroups } = data.group;
+			if (options && ((_options$direction = options.direction) !== null && _options$direction !== void 0 ? _options$direction : "within") === "within") {
+				const target = this.resolveReferenceGroup(options);
+				if (target) return this.mergeGroupFromJSON(data, target, options);
+			}
+			const groupOptions = {
+				id,
+				locked: locked !== null && locked !== void 0 ? locked : false,
+				hideHeader: !!hideHeader,
+				headerPosition,
+				constraints,
+				initialWidth: options === null || options === void 0 ? void 0 : options.initialWidth,
+				initialHeight: options === null || options === void 0 ? void 0 : options.initialHeight,
+				skipSetActive: true
+			};
+			const group = this.addEmptyGroupAt(groupOptions, options);
+			let panels;
+			try {
+				panels = this.deserializePanels(data, group);
+			} catch (err) {
+				this.doRemoveGroup(group, { skipActive: true });
+				throw err;
+			}
+			for (const panel of panels) group.model.openPanel(panel, {
+				skipSetActive: panel.id !== activeView,
+				skipSetGroupActive: true
+			});
+			if (tabGroups && tabGroups.length > 0) group.model.restoreTabGroups(tabGroups);
+			if (!group.activePanel && group.panels.length > 0) group.model.openPanel(group.panels[group.panels.length - 1], { skipSetGroupActive: true });
+			if (!(options === null || options === void 0 ? void 0 : options.skipSetActive)) this.doSetGroupAndPanelActive(group);
+			return group;
+		}
+		/**
+		* Add an empty group at the placement `options` names, or append it
+		* when they name none.
+		*/
+		addEmptyGroupAt(groupOptions, options) {
+			if (options !== void 0 && (isGroupOptionsWithPanel(options) || isGroupOptionsWithGroup(options) || typeof options.direction === "string")) return this._doAddGroup(_objectSpread2$1(_objectSpread2$1({}, options), groupOptions));
+			const group = this.createGroup(groupOptions);
+			this.doAddGroup(group);
+			return group;
+		}
+		/**
+		* Create every panel of a serialized group in `group`, in tab order,
+		* before any is opened, so a corrupt panel state fails before a single
+		* add event has fired (the ordering `fromJSON` uses). On failure the
+		* panels made so far are disposed and the error rethrown.
+		*/
+		deserializePanels(data, group) {
+			const panels = [];
+			try {
+				for (const child of data.group.views) panels.push(this._deserializer.fromJSON(data.panels[child], group));
+			} catch (err) {
+				for (const panel of panels) panel.dispose();
+				throw err;
+			}
+			return panels;
+		}
+		/**
+		* The group an `AddGroupOptions` placement names, or `undefined` for an
+		* absolute placement. Throws for a reference that names nothing.
+		*/
+		resolveReferenceGroup(options) {
+			if (isGroupOptionsWithPanel(options)) {
+				const referencePanelId = typeof options.referencePanel === "string" ? options.referencePanel : options.referencePanel.id;
+				const referencePanel = this.getGroupPanel(referencePanelId);
+				if (!referencePanel) throw new Error(`dockview: reference panel ${referencePanelId} does not exist`);
+				return referencePanel.group;
+			}
+			if (isGroupOptionsWithGroup(options)) {
+				const referenceId = typeof options.referenceGroup === "string" ? options.referenceGroup : options.referenceGroup.id;
+				const referenceGroup = this.getPanel(referenceId);
+				if (!referenceGroup) throw new Error(`dockview: reference group ${referenceId} does not exist`);
+				return referenceGroup;
+			}
+		}
+		/**
+		* The `direction: 'within'` form of `addGroupFromJSON`: the serialized
+		* panels join `target` rather than a group of their own.
+		*/
+		mergeGroupFromJSON(data, target, options) {
+			const { activeView } = data.group;
+			const index = options.index;
+			this.deserializePanels(data, target).forEach((panel, offset) => {
+				target.model.openPanel(panel, {
+					index: index === void 0 ? void 0 : index + offset,
+					skipSetActive: panel.id !== activeView,
+					skipSetGroupActive: true
+				});
+			});
+			if (!options.skipSetActive) this.doSetGroupAndPanelActive(target);
+			return target;
+		}
 		_doAddGroup(options) {
 			if (options) {
 				let referenceGroup;
@@ -18558,10 +18836,26 @@ react_dom = __toESM(react_dom);
 			if (group && this.hasMaximizedGroup() && !this.isMaximizedGroup(group)) this.exitMaximizedGroup();
 			if (!this._moving && activePanel !== ((_this$_onDidActivePan2 = this._onDidActivePanelChange.value) === null || _this$_onDidActivePan2 === void 0 ? void 0 : _this$_onDidActivePan2.panel)) this.fireActivePanelChange(activePanel);
 		}
+		/**
+		* The id for a group created without one: from `groupIdGenerator` when
+		* the option is set, else the sequential counter. An id already in use is
+		* skipped. The counter never repeats, so it can skip any number of live
+		* ids (a restored layout may hold many); a custom generator is given a
+		* bounded number of tries so a broken one cannot hang the call.
+		*/
 		getNextGroupId() {
-			let id = this.nextGroupId.next();
-			while (this._groups.has(id)) id = this.nextGroupId.next();
-			return id;
+			const generate = this.options.groupIdGenerator;
+			if (!generate) {
+				let id = this.nextGroupId.next();
+				while (this._groups.has(id)) id = this.nextGroupId.next();
+				return id;
+			}
+			for (let attempt = 0; attempt < MAX_GROUP_ID_ATTEMPTS; attempt++) {
+				const id = generate();
+				if (typeof id !== "string" || id.length === 0) throw new TypeError("dockview: groupIdGenerator must return a non-empty string");
+				if (!this._groups.has(id)) return id;
+			}
+			throw new Error(`dockview: groupIdGenerator returned an id already in use ${MAX_GROUP_ID_ATTEMPTS} times in a row`);
 		}
 		createGroup(options) {
 			var _options;
@@ -18571,10 +18865,7 @@ react_dom = __toESM(react_dom);
 				console.warn(`dockview: Duplicate group id ${options === null || options === void 0 ? void 0 : options.id}. reassigning group id to avoid errors`);
 				id = void 0;
 			}
-			if (!id) {
-				id = this.nextGroupId.next();
-				while (this._groups.has(id)) id = this.nextGroupId.next();
-			}
+			if (!id) id = this.getNextGroupId();
 			const view = new DockviewGroupPanel(this, id, options);
 			view.init({
 				params: {},