dockview-react 8.6.1 → 8.7.0

package/dist/dockview-react.js

@@ -1,6 +1,6 @@
 /**
  * dockview-react
- * @version 8.6.1
+ * @version 8.7.0
  * @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.1
+	* @version 8.7.0
 	* @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;
@@ -3953,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() {
@@ -6933,9 +6960,11 @@ 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,
+			dropSizing: void 0,
 			theme: void 0,
 			disableTabsOverflowList: void 0,
 			overflow: void 0,
@@ -10461,6 +10490,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;
 		}
@@ -11396,6 +11434,7 @@ react_dom = __toESM(react_dom);
 				nativeEvent: event,
 				position,
 				panel,
+				index,
 				getData: () => getPanelData(),
 				kind: getKind(),
 				group: this.groupPanel,
@@ -11441,6 +11480,7 @@ react_dom = __toESM(react_dom);
 				nativeEvent: event,
 				position,
 				panel,
+				index,
 				getData: () => getPanelData(),
 				group: this.groupPanel,
 				api: this._api
@@ -15656,6 +15696,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);
@@ -17505,7 +17547,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
 					});
@@ -17778,6 +17820,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;
@@ -17919,6 +17987,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;
@@ -18342,7 +18556,7 @@ react_dom = __toESM(react_dom);
 					const [targetParentLocation, to] = tail(targetLocation);
 					if (sourceGroup.api.location.type === "grid" && destinationGridview === this.gridview) {
 						const [sourceParentLocation, from] = tail(getGridLocation(sourceGroup.element));
-						if (sequenceEquals(sourceParentLocation, targetParentLocation)) {
+						if ((this.options.dropSizing !== "distribute" || sourceGroup === destinationGroup) && sequenceEquals(sourceParentLocation, targetParentLocation)) {
 							this.gridview.moveView(sourceParentLocation, from, to);
 							this.fireDidMovePanel(this.getGroupPanel(sourceItemId), sourceGroup);
 							return;
@@ -18372,7 +18586,7 @@ react_dom = __toESM(react_dom);
 						}));
 						this.doRemoveGroup(sourceGroup, { skipActive: true });
 						const updatedTargetLocation = getRelativeLocation(destinationGridview.orientation, getGridLocation(destinationGroup.element), destinationTarget);
-						const newGroup = this.createGroupAtLocation(updatedTargetLocation, this.dropSizing(getGridLocation(destinationGroup.element)), void 0, destinationGridview);
+						const newGroup = this.createGroupAtLocation(updatedTargetLocation, this.sizingForDrop(getGridLocation(destinationGroup.element)), void 0, destinationGridview);
 						this.movingLock(() => newGroup.model.openPanel(removedPanel, { skipSetActive: true }));
 						this.doSetGroupAndPanelActive(newGroup);
 						this.fireDidMovePanel(this.getGroupPanel(sourceItemId), sourceGroup);
@@ -18389,7 +18603,7 @@ react_dom = __toESM(react_dom);
 							skipSetActiveGroup: true
 						}));
 						if (!removedPanel) throw new Error(`dockview: No panel with id ${sourceItemId}`);
-						const newGroup = this.createGroupAtLocation(targetLocation, this.dropSizing(referenceLocation), void 0, destinationGridview);
+						const newGroup = this.createGroupAtLocation(targetLocation, this.sizingForDrop(referenceLocation), void 0, destinationGridview);
 						this.movingLock(() => newGroup.model.openPanel(removedPanel, { skipSetGroupActive: true }));
 						this.doSetGroupAndPanelActive(newGroup);
 						this.fireDidMovePanel(removedPanel, sourceGroup);
@@ -18401,7 +18615,7 @@ react_dom = __toESM(react_dom);
 					}));
 					const updatedReferenceLocation = getGridLocation(destinationGroup.element);
 					const location = getRelativeLocation(destinationGridview.orientation, updatedReferenceLocation, destinationTarget);
-					this.movingLock(() => this.doAddGroup(targetGroup, location, this.dropSizing(updatedReferenceLocation), destinationGridview));
+					this.movingLock(() => this.doAddGroup(targetGroup, location, this.sizingForDrop(updatedReferenceLocation), destinationGridview));
 					this.setGroupLocationForRoot(targetGroup, destinationGridview);
 					this.doSetGroupAndPanelActive(targetGroup);
 					this.fireDidMovePanel(this.getGroupPanel(sourceItemId), sourceGroup);
@@ -18416,7 +18630,7 @@ react_dom = __toESM(react_dom);
 					}));
 					if (!removedPanel) throw new Error(`dockview: No panel with id ${sourceItemId}`);
 					const dropLocation = getRelativeLocation(destinationGridview.orientation, referenceLocation, destinationTarget);
-					const group = this.createGroupAtLocation(dropLocation, this.dropSizing(referenceLocation), void 0, destinationGridview);
+					const group = this.createGroupAtLocation(dropLocation, this.sizingForDrop(referenceLocation), void 0, destinationGridview);
 					this.movingLock(() => group.model.openPanel(removedPanel, { skipSetGroupActive: true }));
 					this.doSetGroupAndPanelActive(group);
 					this.fireDidMovePanel(removedPanel, sourceGroup);
@@ -18460,7 +18674,7 @@ react_dom = __toESM(react_dom);
 			if (!destinationTarget || destinationTarget === "center" || !referenceLocation) targetGroup = destinationGroup;
 			else {
 				const dropLocation = getRelativeLocation(this.gridview.orientation, referenceLocation, destinationTarget);
-				targetGroup = this.createGroupAtLocation(dropLocation, this.dropSizing(referenceLocation));
+				targetGroup = this.createGroupAtLocation(dropLocation, this.sizingForDrop(referenceLocation));
 			}
 			if (!this.keepEmptyGroups(options) && sourceGroup.model.size === 0 && sourceGroup !== targetGroup) this.doRemoveGroup(sourceGroup, { skipActive: true });
 			addPanelsToGroup(targetGroup);
@@ -18592,11 +18806,8 @@ react_dom = __toESM(react_dom);
 					const referenceLocation = getGridLocation(to.element);
 					const dropLocation = getRelativeLocation(destGridview.orientation, referenceLocation, target);
 					let size;
-					if (isReorderWithinBranch) size = getDirectionOrientation(target) === "HORIZONTAL" ? from.api.width : from.api.height;
-					else {
-						var _referenceLocation;
-						size = Sizing.Split((_referenceLocation = referenceLocation[referenceLocation.length - 1]) !== null && _referenceLocation !== void 0 ? _referenceLocation : 0);
-					}
+					if (isReorderWithinBranch && this.options.dropSizing !== "distribute") size = getDirectionOrientation(target) === "HORIZONTAL" ? from.api.width : from.api.height;
+					else size = this.sizingForDrop(referenceLocation);
 					destGridview.addView(source, size, dropLocation);
 					this.setGroupLocationForRoot(source, destGridview);
 				}
@@ -18623,10 +18834,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;
@@ -18636,10 +18863,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: {},
@@ -18721,13 +18945,12 @@ react_dom = __toESM(react_dom);
 			return panel;
 		}
 		/**
-		* Sizing for a group created by a drop next to `referenceLocation`: half
-		* of the group the overlay was drawn over, leaving its siblings alone, so
-		* the panel lands in the region the overlay indicated (#1612). Gridview
-		* rewrites the index to 0 when a cross-axis drop wraps the reference in a
-		* new branch, so one value serves both paths.
+		* Sizing for a group created by a drop next to `referenceLocation`.
+		* Gridview rewrites the index to 0 when a cross-axis drop wraps the
+		* reference in a new branch, so one split index serves both paths.
 		*/
-		dropSizing(referenceLocation) {
+		sizingForDrop(referenceLocation) {
+			if (this.options.dropSizing === "distribute") return Sizing.Distribute;
 			return Sizing.Split(referenceLocation.length === 0 ? 0 : referenceLocation[referenceLocation.length - 1]);
 		}
 		createGroupAtLocation(location, size, options, gridview = this.gridview) {