Merge pull request #812 from mathuo/809-standardize-framework-components-1

chore: align api with existing components

Author: mathuo

packages/dockview-core/src/api/component.api.ts

@@ -40,7 +40,7 @@ import {
 } from '../dockview/dockviewGroupPanel';
 import { Emitter, Event } from '../events';
 import { IDockviewPanel } from '../dockview/dockviewPanel';
-import { PaneviewDropEvent } from '../paneview/draggablePaneviewPanel';
+import { PaneviewDidDropEvent } from '../paneview/draggablePaneviewPanel';
 import {
     GroupDragEvent,
     TabDragEvent,
@@ -51,7 +51,10 @@ import {
     DockviewWillDropEvent,
     WillShowOverlayLocationEvent,
 } from '../dockview/dockviewGroupPanelModel';
-import { PaneviewComponentOptions } from '../paneview/options';
+import {
+    PaneviewComponentOptions,
+    PaneviewDndOverlayEvent,
+} from '../paneview/options';
 import { SplitviewComponentOptions } from '../splitview/options';
 import { GridviewComponentOptions } from '../gridview/options';
 
@@ -294,19 +297,12 @@ export 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<PaneviewDropEvent> {
-        const emitter = new Emitter<PaneviewDropEvent>();
-
-        const disposable = this.component.onDidDrop((e) => {
-            emitter.fire({ ...e, api: this });
-        });
-
-        emitter.dispose = () => {
-            disposable.dispose();
-            emitter.dispose();
-        };
+    get onDidDrop(): Event<PaneviewDidDropEvent> {
+        return this.component.onDidDrop;
+    }
 
-        return emitter.event;
+    get onUnhandledDragOverEvent(): Event<PaneviewDndOverlayEvent> {
+        return this.component.onUnhandledDragOverEvent;
     }
 
     constructor(private readonly component: IPaneviewComponent) {}

packages/dockview-core/src/dockview/options.ts

@@ -16,6 +16,7 @@ import { DockviewPanelRenderer } from '../overlay/overlayRenderContainer';
 import { IGroupHeaderProps } from './framework';
 import { FloatingGroupOptions } from './dockviewComponent';
 import { Contraints } from '../gridview/gridviewPanel';
+import { AcceptableEvent, IAcceptableEvent } from '../events';
 
 export interface IHeaderActionsRenderer extends IDisposable {
     readonly element: HTMLElement;
@@ -65,34 +66,26 @@ export interface DockviewOptions {
     noPanelsOverlay?: 'emptyGroup' | 'watermark';
 }
 
-export interface DockviewDndOverlayEvent {
+export interface DockviewDndOverlayEvent extends IAcceptableEvent {
     nativeEvent: DragEvent;
     target: DockviewGroupDropLocation;
     position: Position;
     group?: DockviewGroupPanel;
     getData: () => PanelTransfer | undefined;
-    //
-    isAccepted: boolean;
-    accept(): void;
 }
 
-export class DockviewUnhandledDragOverEvent implements DockviewDndOverlayEvent {
-    private _isAccepted = false;
-
-    get isAccepted(): boolean {
-        return this._isAccepted;
-    }
-
+export class DockviewUnhandledDragOverEvent
+    extends AcceptableEvent
+    implements DockviewDndOverlayEvent
+{
     constructor(
         readonly nativeEvent: DragEvent,
         readonly target: DockviewGroupDropLocation,
         readonly position: Position,
         readonly getData: () => PanelTransfer | undefined,
         readonly group?: DockviewGroupPanel
-    ) {}
-
-    accept(): void {
-        this._isAccepted = true;
+    ) {
+        super();
     }
 }
 

packages/dockview-core/src/events.ts

@@ -41,6 +41,23 @@ export class DockviewEvent implements IDockviewEvent {
     }
 }
 
+export interface IAcceptableEvent {
+    readonly isAccepted: boolean;
+    accept(): void;
+}
+
+export class AcceptableEvent implements IAcceptableEvent {
+    private _isAccepted = false;
+
+    get isAccepted(): boolean {
+        return this._isAccepted;
+    }
+
+    accept(): void {
+        this._isAccepted = true;
+    }
+}
+
 class LeakageMonitor {
     readonly events = new Map<Event<any>, Stacktrace>();
 

packages/dockview-core/src/index.ts

@@ -41,7 +41,7 @@ export * from './gridview/baseComponentGridview';
 
 export {
     DraggablePaneviewPanel,
-    PaneviewDropEvent,
+    PaneviewDidDropEvent as PaneviewDropEvent,
 } from './paneview/draggablePaneviewPanel';
 
 export * from './dockview/components/panel/content';
@@ -80,6 +80,8 @@ export {
     PaneviewOptions,
     PaneviewFrameworkOptions,
     PROPERTY_KEYS_PANEVIEW,
+    PaneviewUnhandledDragOverEvent,
+    PaneviewDndOverlayEvent,
 } from './paneview/options';
 
 export * from './gridview/gridviewPanel';

packages/dockview-core/src/paneview/draggablePaneviewPanel.ts

@@ -6,17 +6,21 @@ import {
     PaneTransfer,
 } from '../dnd/dataTransfer';
 import { Droptarget, DroptargetEvent } from '../dnd/droptarget';
-import { Emitter } from '../events';
+import { Emitter, Event } from '../events';
 import { IDisposable } from '../lifecycle';
 import { Orientation } from '../splitview/splitview';
+import {
+    PaneviewDndOverlayEvent,
+    PaneviewUnhandledDragOverEvent,
+} from './options';
 import { IPaneviewComponent } from './paneviewComponent';
 import {
     IPaneviewPanel,
     PanePanelInitParameter,
     PaneviewPanel,
 } from './paneviewPanel';
 
-export interface PaneviewDropEvent extends DroptargetEvent {
+export interface PaneviewDidDropEvent extends DroptargetEvent {
     panel: IPaneviewPanel;
     getData: () => PaneTransfer | undefined;
     api: PaneviewApi;
@@ -26,9 +30,14 @@ export abstract class DraggablePaneviewPanel extends PaneviewPanel {
     private handler: DragHandler | undefined;
     private target: Droptarget | undefined;
 
-    private readonly _onDidDrop = new Emitter<PaneviewDropEvent>();
+    private readonly _onDidDrop = new Emitter<PaneviewDidDropEvent>();
     readonly onDidDrop = this._onDidDrop.event;
 
+    private readonly _onUnhandledDragOverEvent =
+        new Emitter<PaneviewDndOverlayEvent>();
+    readonly onUnhandledDragOverEvent: Event<PaneviewDndOverlayEvent> =
+        this._onUnhandledDragOverEvent.event;
+
     constructor(
         private readonly accessor: IPaneviewComponent,
         id: string,
@@ -40,6 +49,8 @@ export abstract class DraggablePaneviewPanel extends PaneviewPanel {
     ) {
         super(id, component, headerComponent, orientation, isExpanded, true);
 
+        this.addDisposables(this._onDidDrop, this._onUnhandledDragOverEvent);
+
         if (!disableDnd) {
             this.initDragFeatures();
         }
@@ -76,7 +87,7 @@ export abstract class DraggablePaneviewPanel extends PaneviewPanel {
             overlayModel: {
                 activationSize: { type: 'percentage', value: 50 },
             },
-            canDisplayOverlay: (event) => {
+            canDisplayOverlay: (event, position) => {
                 const data = getPaneData();
 
                 if (data) {
@@ -88,15 +99,16 @@ export abstract class DraggablePaneviewPanel extends PaneviewPanel {
                     }
                 }
 
-                if (this.accessor.options.showDndOverlay) {
-                    return this.accessor.options.showDndOverlay({
-                        nativeEvent: event,
-                        getData: getPaneData,
-                        panel: this,
-                    });
-                }
+                const firedEvent = new PaneviewUnhandledDragOverEvent(
+                    event,
+                    position,
+                    getPaneData,
+                    this
+                );
+
+                this._onUnhandledDragOverEvent.fire(firedEvent);
 
-                return false;
+                return firedEvent.isAccepted;
             },
         });
 

packages/dockview-core/src/paneview/options.ts

@@ -1,11 +1,12 @@
+import { PaneTransfer } from '../dnd/dataTransfer';
+import { Position } from '../dnd/droptarget';
 import { CreateComponentOptions } from '../dockview/options';
-import { PaneviewDndOverlayEvent } from './paneviewComponent';
-import { IPanePart } from './paneviewPanel';
+import { AcceptableEvent, IAcceptableEvent } from '../events';
+import { IPanePart, IPaneviewPanel } from './paneviewPanel';
 
 export interface PaneviewOptions {
     disableAutoResizing?: boolean;
     disableDnd?: boolean;
-    showDndOverlay?: (event: PaneviewDndOverlayEvent) => boolean;
     className?: string;
 }
 
@@ -27,9 +28,29 @@ export const PROPERTY_KEYS_PANEVIEW: (keyof PaneviewOptions)[] = (() => {
     const properties: Record<keyof PaneviewOptions, undefined> = {
         disableAutoResizing: undefined,
         disableDnd: undefined,
-        showDndOverlay: undefined,
         className: undefined,
     };
 
     return Object.keys(properties) as (keyof PaneviewOptions)[];
 })();
+
+export interface PaneviewDndOverlayEvent extends IAcceptableEvent {
+    nativeEvent: DragEvent;
+    position: Position;
+    panel: IPaneviewPanel;
+    getData: () => PaneTransfer | undefined;
+}
+
+export class PaneviewUnhandledDragOverEvent
+    extends AcceptableEvent
+    implements PaneviewDndOverlayEvent
+{
+    constructor(
+        readonly nativeEvent: DragEvent,
+        readonly position: Position,
+        readonly getData: () => PaneTransfer | undefined,
+        readonly panel: IPaneviewPanel
+    ) {
+        super();
+    }
+}

packages/dockview-core/src/paneview/paneviewComponent.ts

@@ -6,12 +6,12 @@ import {
     MutableDisposable,
 } from '../lifecycle';
 import { LayoutPriority, Orientation, Sizing } from '../splitview/splitview';
-import { PaneviewComponentOptions } from './options';
+import { PaneviewComponentOptions, PaneviewDndOverlayEvent } from './options';
 import { Paneview } from './paneview';
 import { IPanePart, PaneviewPanel, IPaneviewPanel } from './paneviewPanel';
 import {
     DraggablePaneviewPanel,
-    PaneviewDropEvent,
+    PaneviewDidDropEvent,
 } from './draggablePaneviewPanel';
 import { DefaultHeader } from './defaultPaneviewHeader';
 import { sequentialNumberGenerator } from '../math';
@@ -22,12 +22,6 @@ import { Classnames } from '../dom';
 
 const nextLayoutId = sequentialNumberGenerator();
 
-export interface PaneviewDndOverlayEvent {
-    nativeEvent: DragEvent;
-    panel: IPaneviewPanel;
-    getData: () => PaneTransfer | undefined;
-}
-
 export interface SerializedPaneviewPanel {
     snap?: boolean;
     priority?: LayoutPriority;
@@ -106,9 +100,10 @@ export interface IPaneviewComponent extends IDisposable {
     readonly options: PaneviewComponentOptions;
     readonly onDidAddView: Event<PaneviewPanel>;
     readonly onDidRemoveView: Event<PaneviewPanel>;
-    readonly onDidDrop: Event<PaneviewDropEvent>;
+    readonly onDidDrop: Event<PaneviewDidDropEvent>;
     readonly onDidLayoutChange: Event<void>;
     readonly onDidLayoutFromJSON: Event<void>;
+    readonly onUnhandledDragOverEvent: Event<PaneviewDndOverlayEvent>;
     addPanel<T extends object = Parameters>(
         options: AddPaneviewComponentOptions<T>
     ): IPaneviewPanel;
@@ -137,15 +132,20 @@ export class PaneviewComponent extends Resizable implements IPaneviewComponent {
     private readonly _onDidLayoutChange = new Emitter<void>();
     readonly onDidLayoutChange: Event<void> = this._onDidLayoutChange.event;
 
-    private readonly _onDidDrop = new Emitter<PaneviewDropEvent>();
-    readonly onDidDrop: Event<PaneviewDropEvent> = this._onDidDrop.event;
+    private readonly _onDidDrop = new Emitter<PaneviewDidDropEvent>();
+    readonly onDidDrop: Event<PaneviewDidDropEvent> = this._onDidDrop.event;
 
     private readonly _onDidAddView = new Emitter<PaneviewPanel>();
     readonly onDidAddView = this._onDidAddView.event;
 
     private readonly _onDidRemoveView = new Emitter<PaneviewPanel>();
     readonly onDidRemoveView = this._onDidRemoveView.event;
 
+    private readonly _onUnhandledDragOverEvent =
+        new Emitter<PaneviewDndOverlayEvent>();
+    readonly onUnhandledDragOverEvent: Event<PaneviewDndOverlayEvent> =
+        this._onUnhandledDragOverEvent.event;
+
     private readonly _classNames: Classnames;
 
     get id(): string {
@@ -204,7 +204,8 @@ export class PaneviewComponent extends Resizable implements IPaneviewComponent {
             this._onDidLayoutfromJSON,
             this._onDidDrop,
             this._onDidAddView,
-            this._onDidRemoveView
+            this._onDidRemoveView,
+            this._onUnhandledDragOverEvent
         );
 
         this._classNames = new Classnames(this.element);
@@ -442,9 +443,14 @@ export class PaneviewComponent extends Resizable implements IPaneviewComponent {
     }
 
     private doAddPanel(panel: PaneFramework): void {
-        const disposable = panel.onDidDrop((event) => {
-            this._onDidDrop.fire(event);
-        });
+        const disposable = new CompositeDisposable(
+            panel.onDidDrop((event) => {
+                this._onDidDrop.fire(event);
+            }),
+            panel.onUnhandledDragOverEvent((event) => {
+                this._onUnhandledDragOverEvent.fire(event);
+            })
+        );
 
         this._viewDisposables.set(panel.id, disposable);
     }

packages/dockview/src/paneview/paneview.tsx

@@ -1,7 +1,6 @@
 import React from 'react';
 import {
     PaneviewPanelApi,
-    PaneviewDndOverlayEvent,
     PaneviewApi,
     PaneviewDropEvent,
     createPaneview,
@@ -32,7 +31,6 @@ export interface IPaneviewReactProps extends PaneviewOptions {
         string,
         React.FunctionComponent<IPaneviewPanelProps>
     >;
-    showDndOverlay?: (event: PaneviewDndOverlayEvent) => boolean;
     onDidDrop?(event: PaneviewDropEvent): void;
 }
 
@@ -177,15 +175,6 @@ export const PaneviewReact = React.forwardRef(
             };
         }, [props.onDidDrop]);
 
-        React.useEffect(() => {
-            if (!paneviewRef.current) {
-                return;
-            }
-            paneviewRef.current.updateOptions({
-                showDndOverlay: props.showDndOverlay,
-            });
-        }, [props.showDndOverlay]);
-
         return (
             <div
                 className={props.className}

packages/docs/docs/advanced/nested.mdx

@@ -8,6 +8,6 @@ import { CodeRunner } from '@site/src/components/ui/codeRunner';
 # Nested Dockviews
 
 You can safely create multiple dockview instances within one page and nest dockviews within other dockviews.
-If you wish to interact with the drop event from one dockview instance in another dockview instance you can implement the `showDndOverlay` and `onDidDrop` props on `DockviewReact`.
+If you wish to interact with the drop event from one dockview instance in another dockview instance you can implement the `api.onUnhandledDragOverEvent` and `onDidDrop` props on `DockviewReact`.
 
 <CodeRunner id="dockview/nested" />