dockview-core 6.6.0 → 7.0.2

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
 <h1>dockview-core</h1>
 
-<p>Framework-agnostic core layout engine — zero dependencies, vanilla TypeScript. Supports tabs, groups, grids and splitviews</p>
+<p>Framework-agnostic core layout engine — zero dependencies, JavaScript. Supports tabs, groups, grids and splitviews</p>
 
 </div>
 
@@ -20,6 +20,13 @@
 
 Please see the website: https://dockview.dev
 
+> **`dockview-core` is an internal package.** Install
+> **[`dockview`](https://www.npmjs.com/package/dockview)** instead — the JavaScript
+> JavaScript / TypeScript package that ships the full feature set out of the box. Using a
+> framework? Install the bindings: [`dockview-react`](https://www.npmjs.com/package/dockview-react),
+> [`dockview-vue`](https://www.npmjs.com/package/dockview-vue) or
+> [`dockview-angular`](https://www.npmjs.com/package/dockview-angular).
+
 ## Features
 
 -   Serialization / deserialization with full layout management

package/dist/cjs/api/component.api.d.ts

@@ -1,8 +1,8 @@
-import { DockviewMaximizedGroupChanged, FloatingGroupOptions, IDockviewComponent, MovePanelEvent, PopoutGroupChangePositionEvent, PopoutGroupChangeSizeEvent, SerializedDockview } from '../dockview/dockviewComponent';
+import { DockviewActivePanelChangeEvent, DockviewLayoutMutationEvent, DockviewMaximizedGroupChangeEvent, DockviewPopoutGroupOptions, FloatingGroupOptions, GroupNavigationDirection, IDockviewComponent, MovePanelEvent, PopoutGroup, PopoutGroupChangePositionEvent, PopoutGroupChangeSizeEvent, SerializedDockview } from '../dockview/dockviewComponent';
 import { AddGroupOptions, AddPanelOptions, DockviewComponentOptions, DockviewDndOverlayEvent, MovementOptions } from '../dockview/options';
 import { Parameters } from '../panel/types';
 import { Direction } from '../gridview/baseComponentGridview';
-import { AddComponentOptions, IGridviewComponent, SerializedGridviewComponent } from '../gridview/gridviewComponent';
+import { AddGridviewComponentOptions, IGridviewComponent, SerializedGridviewComponent } from '../gridview/gridviewComponent';
 import { IGridviewPanel } from '../gridview/gridviewPanel';
 import { AddPaneviewComponentOptions, SerializedPaneview, IPaneviewComponent } from '../paneview/paneviewComponent';
 import { IPaneviewPanel } from '../paneview/paneviewPanel';
@@ -14,7 +14,6 @@ import { Event } from '../events';
 import { IDockviewPanel } from '../dockview/dockviewPanel';
 import { PaneviewDidDropEvent } from '../paneview/draggablePaneviewPanel';
 import { GroupDragEvent, TabDragEvent } from '../dockview/components/titlebar/tabsContainer';
-import { Box } from '../types';
 import { DockviewDidDropEvent, DockviewWillDropEvent } from '../dockview/dockviewGroupPanelModel';
 import { DockviewWillShowOverlayLocationEvent, DockviewTabGroupChangeEvent, DockviewTabGroupCollapsedChangeEvent, DockviewTabGroupPanelChangeEvent } from '../dockview/events';
 import { ITabGroup } from '../dockview/tabGroup';
@@ -170,7 +169,7 @@ export declare class PaneviewApi implements CommonApi<SerializedPaneview> {
      * Invoked when a Drag'n'Drop event occurs that the component was unable to handle. Exposed for custom Drag'n'Drop functionality.
      */
     get onDidDrop(): Event<PaneviewDidDropEvent>;
-    get onUnhandledDragOverEvent(): Event<PaneviewDndOverlayEvent>;
+    get onUnhandledDragOver(): Event<PaneviewDndOverlayEvent>;
     constructor(component: IPaneviewComponent);
     /**
      * Remove a panel given the panel object.
@@ -284,7 +283,7 @@ export declare class GridviewApi implements CommonApi<SerializedGridviewComponen
     /**
      * Add a panel and return the created object.
      */
-    addPanel<T extends object = Parameters>(options: AddComponentOptions<T>): IGridviewPanel;
+    addPanel<T extends object = Parameters>(options: AddGridviewComponentOptions<T>): IGridviewPanel;
     /**
      * Remove a panel given the panel object.
      */
@@ -380,9 +379,11 @@ export declare class DockviewApi implements CommonApi<SerializedDockview> {
      */
     get onDidRemoveGroup(): Event<DockviewGroupPanel>;
     /**
-     * Invoked when the active panel changes. May be undefined if no panel is active.
+     * Invoked when the active panel changes. The event carries the active
+     * `panel` (may be undefined if no panel is active) and the
+     * {@link DockviewOrigin} (`'user'` vs `'api'`) of the change.
      */
-    get onDidActivePanelChange(): Event<IDockviewPanel | undefined>;
+    get onDidActivePanelChange(): Event<DockviewActivePanelChangeEvent>;
     /**
      * Invoked when a panel is added. May be called multiple times when moving panels.
      */
@@ -411,6 +412,15 @@ export declare class DockviewApi implements CommonApi<SerializedDockview> {
      * Preventing certain events may causes unexpected behaviours, use carefully.
      */
     get onWillDrop(): Event<DockviewWillDropEvent>;
+    /**
+     * Fires before each top-level structural layout mutation (add / remove /
+     * move / float / popout / maximize / load / clear). Compound operations
+     * (e.g. a drag) fire once. Pair with `onDidMutateLayout` to bracket a
+     * change — useful for undo/redo, autosave and dirty-tracking.
+     */
+    get onWillMutateLayout(): Event<DockviewLayoutMutationEvent>;
+    /** Fires after each top-level structural layout mutation. See `onWillMutateLayout`. */
+    get onDidMutateLayout(): Event<DockviewLayoutMutationEvent>;
     /**
      * Invoked before an overlay is shown indicating a drop target.
      *
@@ -431,10 +441,24 @@ export declare class DockviewApi implements CommonApi<SerializedDockview> {
      * Calling `event.nativeEvent.preventDefault()` will prevent the panel drag starting.
      */
     get onWillDragPanel(): Event<TabDragEvent>;
-    get onUnhandledDragOverEvent(): Event<DockviewDndOverlayEvent>;
+    get onUnhandledDragOver(): Event<DockviewDndOverlayEvent>;
     get onDidPopoutGroupSizeChange(): Event<PopoutGroupChangeSizeEvent>;
     get onDidPopoutGroupPositionChange(): Event<PopoutGroupChangePositionEvent>;
+    /**
+     * Fires when a popout group successfully opens in its own window, carrying
+     * the live `Window` handle. Use it to route focus or attach per-document
+     * listeners. Enumerate the current popouts at any time with `getPopouts()`.
+     */
+    get onDidAddPopoutGroup(): Event<PopoutGroup>;
+    /**
+     * Fires when a popout group is removed — whether the user closed its window
+     * or it was docked back programmatically. Symmetric with
+     * {@link onDidAddPopoutGroup}; not fired during component disposal.
+     */
+    get onDidRemovePopoutGroup(): Event<PopoutGroup>;
     get onDidOpenPopoutWindowFail(): Event<void>;
+    /** Enumerate the popout groups currently open in their own windows. */
+    getPopouts(): PopoutGroup[];
     /**
      * Invoked when a tab group is created in any group.
      */
@@ -467,6 +491,14 @@ export declare class DockviewApi implements CommonApi<SerializedDockview> {
      * All group objects.
      */
     get groups(): DockviewGroupPanel[];
+    /**
+     * The nearest grid group in a spatial direction from `group`, comparing
+     * group centre points — e.g. the group visually to the left. Floating and
+     * popout groups are ignored. Returns `undefined` when there is no group in
+     * that direction. Pair with `group.api.boundingBox` to build your own
+     * spatial navigation.
+     */
+    adjacentGroupInDirection(group: IDockviewGroupPanel, direction: GroupNavigationDirection): IDockviewGroupPanel | undefined;
     /**
      *  Active panel object.
      */
@@ -541,22 +573,11 @@ export declare class DockviewApi implements CommonApi<SerializedDockview> {
     maximizeGroup(panel: IDockviewPanel): void;
     hasMaximizedGroup(): boolean;
     exitMaximizedGroup(): void;
-    get onDidMaximizedGroupChange(): Event<DockviewMaximizedGroupChanged>;
+    get onDidMaximizedGroupChange(): Event<DockviewMaximizedGroupChangeEvent>;
     /**
      * Add a popout group in a new Window
      */
-    addPopoutGroup(item: IDockviewPanel | DockviewGroupPanel, options?: {
-        position?: Box;
-        popoutUrl?: string;
-        onDidOpen?: (event: {
-            id: string;
-            window: Window;
-        }) => void;
-        onWillClose?: (event: {
-            id: string;
-            window: Window;
-        }) => void;
-    }): Promise<boolean>;
+    addPopoutGroup(item: IDockviewPanel | DockviewGroupPanel, options?: DockviewPopoutGroupOptions): Promise<boolean>;
     /**
      * Add an edge group at the given position. Returns the group panel API
      * for the newly created group. Throws if a group already exists there.

package/dist/cjs/api/component.api.js

@@ -288,9 +288,9 @@ var PaneviewApi = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
-    Object.defineProperty(PaneviewApi.prototype, "onUnhandledDragOverEvent", {
+    Object.defineProperty(PaneviewApi.prototype, "onUnhandledDragOver", {
         get: function () {
-            return this.component.onUnhandledDragOverEvent;
+            return this.component.onUnhandledDragOver;
         },
         enumerable: false,
         configurable: true
@@ -707,7 +707,9 @@ var DockviewApi = /** @class */ (function () {
     });
     Object.defineProperty(DockviewApi.prototype, "onDidActivePanelChange", {
         /**
-         * Invoked when the active panel changes. May be undefined if no panel is active.
+         * Invoked when the active panel changes. The event carries the active
+         * `panel` (may be undefined if no panel is active) and the
+         * {@link DockviewOrigin} (`'user'` vs `'api'`) of the change.
          */
         get: function () {
             return this.component.onDidActivePanelChange;
@@ -785,6 +787,27 @@ var DockviewApi = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    Object.defineProperty(DockviewApi.prototype, "onWillMutateLayout", {
+        /**
+         * Fires before each top-level structural layout mutation (add / remove /
+         * move / float / popout / maximize / load / clear). Compound operations
+         * (e.g. a drag) fire once. Pair with `onDidMutateLayout` to bracket a
+         * change — useful for undo/redo, autosave and dirty-tracking.
+         */
+        get: function () {
+            return this.component.onWillMutateLayout;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(DockviewApi.prototype, "onDidMutateLayout", {
+        /** Fires after each top-level structural layout mutation. See `onWillMutateLayout`. */
+        get: function () {
+            return this.component.onDidMutateLayout;
+        },
+        enumerable: false,
+        configurable: true
+    });
     Object.defineProperty(DockviewApi.prototype, "onWillShowOverlay", {
         /**
          * Invoked before an overlay is shown indicating a drop target.
@@ -823,9 +846,9 @@ var DockviewApi = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
-    Object.defineProperty(DockviewApi.prototype, "onUnhandledDragOverEvent", {
+    Object.defineProperty(DockviewApi.prototype, "onUnhandledDragOver", {
         get: function () {
-            return this.component.onUnhandledDragOverEvent;
+            return this.component.onUnhandledDragOver;
         },
         enumerable: false,
         configurable: true
@@ -844,6 +867,30 @@ var DockviewApi = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    Object.defineProperty(DockviewApi.prototype, "onDidAddPopoutGroup", {
+        /**
+         * Fires when a popout group successfully opens in its own window, carrying
+         * the live `Window` handle. Use it to route focus or attach per-document
+         * listeners. Enumerate the current popouts at any time with `getPopouts()`.
+         */
+        get: function () {
+            return this.component.onDidAddPopoutGroup;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(DockviewApi.prototype, "onDidRemovePopoutGroup", {
+        /**
+         * Fires when a popout group is removed — whether the user closed its window
+         * or it was docked back programmatically. Symmetric with
+         * {@link onDidAddPopoutGroup}; not fired during component disposal.
+         */
+        get: function () {
+            return this.component.onDidRemovePopoutGroup;
+        },
+        enumerable: false,
+        configurable: true
+    });
     Object.defineProperty(DockviewApi.prototype, "onDidOpenPopoutWindowFail", {
         get: function () {
             return this.component.onDidOpenPopoutWindowFail;
@@ -851,6 +898,10 @@ var DockviewApi = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    /** Enumerate the popout groups currently open in their own windows. */
+    DockviewApi.prototype.getPopouts = function () {
+        return this.component.getPopouts();
+    };
     Object.defineProperty(DockviewApi.prototype, "onDidCreateTabGroup", {
         /**
          * Invoked when a tab group is created in any group.
@@ -931,6 +982,16 @@ var DockviewApi = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    /**
+     * The nearest grid group in a spatial direction from `group`, comparing
+     * group centre points — e.g. the group visually to the left. Floating and
+     * popout groups are ignored. Returns `undefined` when there is no group in
+     * that direction. Pair with `group.api.boundingBox` to build your own
+     * spatial navigation.
+     */
+    DockviewApi.prototype.adjacentGroupInDirection = function (group, direction) {
+        return this.component.adjacentGroupInDirection(group, direction);
+    };
     Object.defineProperty(DockviewApi.prototype, "activePanel", {
         /**
          *  Active panel object.
@@ -974,13 +1035,19 @@ var DockviewApi = /** @class */ (function () {
      * Add a panel and return the created object.
      */
     DockviewApi.prototype.addPanel = function (options) {
-        return this.component.addPanel(options);
+        var _this = this;
+        return this.component.withOrigin('api', function () {
+            return _this.component.addPanel(options);
+        });
     };
     /**
      * Remove a panel given the panel object.
      */
     DockviewApi.prototype.removePanel = function (panel) {
-        this.component.removePanel(panel);
+        var _this = this;
+        this.component.withOrigin('api', function () {
+            return _this.component.removePanel(panel);
+        });
     };
     /**
      * Add a group and return the created object.
@@ -992,13 +1059,19 @@ var DockviewApi = /** @class */ (function () {
      * Close all groups and panels.
      */
     DockviewApi.prototype.closeAllGroups = function () {
-        return this.component.closeAllGroups();
+        var _this = this;
+        return this.component.withOrigin('api', function () {
+            return _this.component.closeAllGroups();
+        });
     };
     /**
      * Remove a group and any panels within the group.
      */
     DockviewApi.prototype.removeGroup = function (group) {
-        this.component.removeGroup(group);
+        var _this = this;
+        this.component.withOrigin('api', function () {
+            return _this.component.removeGroup(group);
+        });
     };
     /**
      * Get a group object given a `string` id. May return undefined.
@@ -1010,13 +1083,19 @@ var DockviewApi = /** @class */ (function () {
      * Add a floating group
      */
     DockviewApi.prototype.addFloatingGroup = function (item, options) {
-        return this.component.addFloatingGroup(item, options);
+        var _this = this;
+        return this.component.withOrigin('api', function () {
+            return _this.component.addFloatingGroup(item, options);
+        });
     };
     /**
      * Create a component from a serialized object.
      */
     DockviewApi.prototype.fromJSON = function (data, options) {
-        this.component.fromJSON(data, options);
+        var _this = this;
+        this.component.withOrigin('api', function () {
+            return _this.component.fromJSON(data, options);
+        });
     };
     /**
      * Create a serialized object of the current component.
@@ -1028,7 +1107,8 @@ var DockviewApi = /** @class */ (function () {
      * Reset the component back to an empty and default state.
      */
     DockviewApi.prototype.clear = function () {
-        this.component.clear();
+        var _this = this;
+        this.component.withOrigin('api', function () { return _this.component.clear(); });
     };
     /**
      * Move the focus progmatically to the next panel or group.
@@ -1062,7 +1142,10 @@ var DockviewApi = /** @class */ (function () {
      * Add a popout group in a new Window
      */
     DockviewApi.prototype.addPopoutGroup = function (item, options) {
-        return this.component.addPopoutGroup(item, options);
+        var _this = this;
+        return this.component.withOrigin('api', function () {
+            return _this.component.addPopoutGroup(item, options);
+        });
     };
     /**
      * Add an edge group at the given position. Returns the group panel API
@@ -1110,23 +1193,31 @@ var DockviewApi = /** @class */ (function () {
     };
     DockviewApi.prototype.createTabGroup = function (options) {
         var model = this._getGroupModel(options.groupId);
-        return model.createTabGroup({
-            label: options.label,
-            color: options.color,
-            componentParams: options.componentParams,
+        return this.component.withOrigin('api', function () {
+            return model.createTabGroup({
+                label: options.label,
+                color: options.color,
+                componentParams: options.componentParams,
+            });
         });
     };
     DockviewApi.prototype.dissolveTabGroup = function (options) {
         var model = this._getGroupModel(options.groupId);
-        model.dissolveTabGroup(options.tabGroupId);
+        this.component.withOrigin('api', function () {
+            return model.dissolveTabGroup(options.tabGroupId);
+        });
     };
     DockviewApi.prototype.addPanelToTabGroup = function (options) {
         var model = this._getGroupModel(options.groupId);
-        model.addPanelToTabGroup(options.tabGroupId, options.panelId, options.index);
+        this.component.withOrigin('api', function () {
+            return model.addPanelToTabGroup(options.tabGroupId, options.panelId, options.index);
+        });
     };
     DockviewApi.prototype.removePanelFromTabGroup = function (options) {
         var model = this._getGroupModel(options.groupId);
-        model.removePanelFromTabGroup(options.panelId);
+        this.component.withOrigin('api', function () {
+            return model.removePanelFromTabGroup(options.panelId);
+        });
     };
     DockviewApi.prototype.getTabGroups = function (options) {
         var model = this._getGroupModel(options.groupId);

package/dist/cjs/api/dockviewGroupPanelApi.d.ts

@@ -1,7 +1,8 @@
 import { Position } from '../dnd/droptarget';
 import { DockviewComponent } from '../dockview/dockviewComponent';
+import { Box } from '../types';
 import { DockviewGroupPanel } from '../dockview/dockviewGroupPanel';
-import { DockviewGroupChangeEvent, DockviewGroupLocation, DockviewGroupPanelLocked } from '../dockview/dockviewGroupPanelModel';
+import { DockviewGroupActivePanelChangeEvent, DockviewGroupLocation, DockviewGroupPanelLocked } from '../dockview/dockviewGroupPanelModel';
 import { DockviewHeaderPosition } from '../dockview/options';
 import { Emitter, Event } from '../events';
 import { GridviewPanelApi, GridviewPanelApiImpl, SizeEvent } from './gridviewPanelApi';
@@ -21,8 +22,15 @@ export interface DockviewGroupPanelCollapsedChangeEvent {
     readonly isCollapsed: boolean;
 }
 export interface DockviewGroupPanelApi extends GridviewPanelApi {
-    readonly onDidLocationChange: Event<DockviewGroupPanelFloatingChangeEvent>;
-    readonly onDidActivePanelChange: Event<DockviewGroupChangeEvent>;
+    readonly onDidLocationChange: Event<DockviewGroupPanelLocationChangeEvent>;
+    /**
+     * Fires when the active panel *within this group* changes. Scoped to the
+     * group, in contrast to the component-level
+     * `DockviewApi.onDidActivePanelChange` (which tracks the active panel across
+     * the whole dockview). Both carry an {@link DockviewOrigin} reporting
+     * whether the change came from a user gesture or an API call.
+     */
+    readonly onDidActivePanelChange: Event<DockviewGroupActivePanelChangeEvent>;
     /**
      * Fired when an edge group's collapsed state changes.
      * Never fires for non-edge groups.
@@ -61,20 +69,27 @@ export interface DockviewGroupPanelApi extends GridviewPanelApi {
      */
     isCollapsed(): boolean;
 }
-export interface DockviewGroupPanelFloatingChangeEvent {
+export interface DockviewGroupPanelLocationChangeEvent {
     readonly location: DockviewGroupLocation;
 }
 export declare class DockviewGroupPanelApiImpl extends GridviewPanelApiImpl {
     private readonly accessor;
     private _group;
     private _pendingSize;
-    readonly _onDidLocationChange: Emitter<DockviewGroupPanelFloatingChangeEvent>;
-    readonly onDidLocationChange: Event<DockviewGroupPanelFloatingChangeEvent>;
-    readonly _onDidActivePanelChange: Emitter<DockviewGroupChangeEvent>;
-    readonly onDidActivePanelChange: Event<DockviewGroupChangeEvent>;
+    readonly _onDidLocationChange: Emitter<DockviewGroupPanelLocationChangeEvent>;
+    readonly onDidLocationChange: Event<DockviewGroupPanelLocationChangeEvent>;
+    readonly _onDidActivePanelChange: Emitter<DockviewGroupActivePanelChangeEvent>;
+    readonly onDidActivePanelChange: Event<DockviewGroupActivePanelChangeEvent>;
     readonly _onDidCollapsedChange: Emitter<DockviewGroupPanelCollapsedChangeEvent>;
     readonly onDidCollapsedChange: Event<DockviewGroupPanelCollapsedChangeEvent>;
     get location(): DockviewGroupLocation;
+    /**
+     * The group's bounding box relative to the top-left of the dockview root,
+     * in pixels. Covers grid and floating groups; returns `undefined` for a
+     * popout group (it lives in a separate window). Reflects the live rendered
+     * geometry, so it is only meaningful once the layout has been sized.
+     */
+    get boundingBox(): Box | undefined;
     get locked(): DockviewGroupPanelLocked;
     set locked(value: DockviewGroupPanelLocked);
     constructor(id: string, accessor: DockviewComponent);

package/dist/cjs/api/dockviewGroupPanelApi.js

@@ -61,6 +61,29 @@ var DockviewGroupPanelApiImpl = /** @class */ (function (_super) {
         enumerable: false,
         configurable: true
     });
+    Object.defineProperty(DockviewGroupPanelApiImpl.prototype, "boundingBox", {
+        /**
+         * The group's bounding box relative to the top-left of the dockview root,
+         * in pixels. Covers grid and floating groups; returns `undefined` for a
+         * popout group (it lives in a separate window). Reflects the live rendered
+         * geometry, so it is only meaningful once the layout has been sized.
+         */
+        get: function () {
+            if (!this._group || this._group.model.location.type === 'popout') {
+                return undefined;
+            }
+            var root = this.accessor.element.getBoundingClientRect();
+            var rect = this._group.element.getBoundingClientRect();
+            return {
+                left: rect.left - root.left,
+                top: rect.top - root.top,
+                width: rect.width,
+                height: rect.height,
+            };
+        },
+        enumerable: false,
+        configurable: true
+    });
     Object.defineProperty(DockviewGroupPanelApiImpl.prototype, "locked", {
         get: function () {
             if (!this._group) {

package/dist/cjs/api/dockviewPanelApi.d.ts

@@ -4,7 +4,7 @@ import { DockviewGroupPanel } from '../dockview/dockviewGroupPanel';
 import { DockviewPanel } from '../dockview/dockviewPanel';
 import { DockviewComponent } from '../dockview/dockviewComponent';
 import { DockviewPanelRenderer } from '../overlay/overlayRenderContainer';
-import { DockviewGroupMoveParams, DockviewGroupPanelFloatingChangeEvent } from './dockviewGroupPanelApi';
+import { DockviewGroupMoveParams, DockviewGroupPanelLocationChangeEvent } from './dockviewGroupPanelApi';
 import { DockviewGroupLocation } from '../dockview/dockviewGroupPanelModel';
 export interface TitleEvent {
     readonly title: string;
@@ -34,7 +34,7 @@ export interface DockviewPanelApi extends Omit<GridviewPanelApi, 'setVisible' |
     readonly onDidTitleChange: Event<TitleEvent>;
     readonly onDidRendererChange: Event<RendererChangedEvent>;
     readonly location: DockviewGroupLocation;
-    readonly onDidLocationChange: Event<DockviewGroupPanelFloatingChangeEvent>;
+    readonly onDidLocationChange: Event<DockviewGroupPanelLocationChangeEvent>;
     close(): void;
     setTitle(title: string): void;
     setRenderer(renderer: DockviewPanelRenderer): void;
@@ -61,7 +61,7 @@ export declare class DockviewPanelApiImpl extends GridviewPanelApiImpl implement
     readonly _onDidRendererChange: Emitter<RendererChangedEvent>;
     readonly onDidRendererChange: Event<RendererChangedEvent>;
     private readonly _onDidLocationChange;
-    readonly onDidLocationChange: Event<DockviewGroupPanelFloatingChangeEvent>;
+    readonly onDidLocationChange: Event<DockviewGroupPanelLocationChangeEvent>;
     private readonly groupEventsDisposable;
     get location(): DockviewGroupLocation;
     get title(): string | undefined;
@@ -72,6 +72,7 @@ export declare class DockviewPanelApiImpl extends GridviewPanelApiImpl implement
     get tabComponent(): string | undefined;
     constructor(panel: DockviewPanel, group: DockviewGroupPanel, accessor: DockviewComponent, component: string, tabComponent?: string);
     getWindow(): Window;
+    setActive(): void;
     moveTo(options: DockviewPanelMoveParams): void;
     setTitle(title: string): void;
     setRenderer(renderer: DockviewPanelRenderer): void;

package/dist/cjs/api/dockviewPanelApi.js

@@ -99,6 +99,14 @@ var DockviewPanelApiImpl = /** @class */ (function (_super) {
     DockviewPanelApiImpl.prototype.getWindow = function () {
         return this.group.api.getWindow();
     };
+    DockviewPanelApiImpl.prototype.setActive = function () {
+        var _this = this;
+        // A bare `panel.api.setActive()` from application code is a
+        // programmatic activation. Tag it `'api'` so `onDidActivePanelChange`
+        // reports the correct origin; user-gesture call sites that route
+        // through here wrap the call in `withOrigin('user')` first, which wins.
+        this.accessor.withOrigin('api', function () { return _super.prototype.setActive.call(_this); });
+    };
     DockviewPanelApiImpl.prototype.moveTo = function (options) {
         var _a, _b;
         this.accessor.moveGroupOrPanel({

package/dist/cjs/dnd/droptarget.d.ts

@@ -103,6 +103,14 @@ export declare class Droptarget extends CompositeDisposable implements IDropTarg
     private toggleClasses;
     private calculateQuadrant;
     private removeDropTarget;
+    /**
+     * Render the drop overlay at `position` without a live drag, so keyboard
+     * docking shows the exact same preview as a mouse drag. Mirrors the
+     * `onDragOver` render path (in-place or anchored). Pair with `clearOverlay`.
+     */
+    showOverlay(position: Position): void;
+    /** Clear an overlay shown via {@link showOverlay} (in-place or anchored). */
+    clearOverlay(): void;
 }
 export declare function calculateQuadrantAsPercentage(overlayType: Set<Position>, x: number, y: number, width: number, height: number, threshold: number): Position | null;
 export declare function calculateQuadrantAsPixels(overlayType: Set<Position>, x: number, y: number, width: number, height: number, threshold: number): Position | null;

package/dist/cjs/dnd/droptarget.js

@@ -290,6 +290,34 @@ var Droptarget = /** @class */ (function (_super) {
             this.overlayElement = undefined;
         }
     };
+    /**
+     * Render the drop overlay at `position` without a live drag, so keyboard
+     * docking shows the exact same preview as a mouse drag. Mirrors the
+     * `onDragOver` render path (in-place or anchored). Pair with `clearOverlay`.
+     */
+    Droptarget.prototype.showOverlay = function (position) {
+        var _a, _b, _c, _d, _e;
+        var overrideTarget = (_b = (_a = this.options).getOverrideTarget) === null || _b === void 0 ? void 0 : _b.call(_a);
+        var target = (_e = (_d = (_c = this.options).getOverlayOutline) === null || _d === void 0 ? void 0 : _d.call(_c)) !== null && _e !== void 0 ? _e : this.element;
+        var width = target.offsetWidth;
+        var height = target.offsetHeight;
+        if (!overrideTarget && !this.targetElement) {
+            var els = (0, dropOverlay_1.createOverlayElements)();
+            this.targetElement = els.dropzone;
+            this.overlayElement = els.selection;
+            target.classList.add('dv-drop-target');
+            target.append(this.targetElement);
+        }
+        this.toggleClasses(position, width, height);
+        this._state = position;
+    };
+    /** Clear an overlay shown via {@link showOverlay} (in-place or anchored). */
+    Droptarget.prototype.clearOverlay = function () {
+        var _a, _b, _c;
+        this.removeDropTarget();
+        (_c = (_b = (_a = this.options).getOverrideTarget) === null || _b === void 0 ? void 0 : _b.call(_a)) === null || _c === void 0 ? void 0 : _c.clear();
+        this._state = undefined;
+    };
     Droptarget.USED_EVENT_ID = '__dockview_droptarget_event_is_used__';
     return Droptarget;
 }(lifecycle_1.CompositeDisposable));

package/dist/cjs/dockview/accessibilityMessages.d.ts

@@ -0,0 +1,32 @@
+import { Position } from '../dnd/droptarget';
+/**
+ * The full set of localisable strings dockview speaks to assistive technology:
+ * the LiveRegion announcements and the keyboard-docking narration. Each entry
+ * returns the complete sentence so a translator owns wording *and* word order.
+ *
+ * Override any subset via the `messages` option; unset entries keep the
+ * English defaults below. For fine-grained, per-event announcement overrides
+ * (with access to the panel) use `getAnnouncement`, which takes precedence.
+ */
+export interface DockviewMessages {
+    panelOpened(title: string): string;
+    panelClosed(title: string): string;
+    groupMaximized(title: string): string;
+    groupRestored(title: string): string;
+    groupFloated(title: string): string;
+    groupDocked(title: string): string;
+    groupPoppedOut(title: string): string;
+    /** Target phase: which group is highlighted, and how to proceed. */
+    movePickTarget(source: string, target: string, current: number, total: number): string;
+    /** Edge phase: which drop position is selected, and how to proceed. */
+    movePickEdge(position: Position, target: string): string;
+    /** A move committed. */
+    moveCommitted(source: string, target: string, position: Position): string;
+    /** A move cancelled with Escape. */
+    moveCancelled(): string;
+    /** A move the layout rejected. */
+    moveNotAllowed(): string;
+}
+export declare const DEFAULT_MESSAGES: DockviewMessages;
+/** Merge an app's partial overrides over the English defaults. */
+export declare function resolveMessages(overrides?: Partial<DockviewMessages>): DockviewMessages;