@xh/hoist 79.0.0-SNAPSHOT.1764947672059 → 79.0.0-SNAPSHOT.1764952313480

package/build/types/desktop/cmp/dash/canvas/DashCanvas.d.ts

@@ -1,6 +1,6 @@
+import { type ReactGridLayoutProps } from 'react-grid-layout';
 import { HoistProps, TestSupportProps } from '@xh/hoist/core';
 import '@xh/hoist/desktop/register';
-import type { ReactGridLayoutProps } from 'react-grid-layout';
 import { DashCanvasModel } from './DashCanvasModel';
 import 'react-grid-layout/css/styles.css';
 import './DashCanvas.scss';

package/build/types/desktop/cmp/dash/canvas/DashCanvasModel.d.ts

@@ -1,3 +1,4 @@
+import type { DragOverEvent, Layout } from 'react-grid-layout';
 import { Persistable, PersistableState } from '@xh/hoist/core';
 import { DashCanvasViewModel, DashCanvasViewSpec, DashConfig, DashViewState, DashModel } from '../';
 import '@xh/hoist/desktop/register';
@@ -20,6 +21,30 @@ export interface DashCanvasConfig extends DashConfig<DashCanvasViewSpec, DashCan
     maxRows?: number;
     /** Padding inside the container [x, y] in pixels. Defaults to same as `margin`. */
     containerPadding?: [number, number];
+    /**
+     * Whether the canvas should accept drag-and-drop of views from outside
+     * the canvas. Default false.
+     */
+    droppable?: boolean;
+    /**
+     * Optional Callback to invoke after a view is successfully dropped onto the canvas.
+     */
+    onDropDone?: (viewModel: DashCanvasViewModel) => void;
+    /**
+     * Optional callback to invoke when an item is dragged over the canvas. This may be used to
+     * customize how the size of the dropping placeholder is calculated. The callback should
+     * return an object with optional 'w' and 'h' properties indicating the desired width and height
+     * (in grid units) of the dropping placeholder. If not provided, Hoist's own default logic will be used.
+     */
+    onDropDragOver?: (e: DragOverEvent) => {
+        w?: number;
+        h?: number;
+    } | false | undefined;
+    /**
+     * Whether an overlay with an Add View button should be rendered
+     * when the canvas is empty. Default true.
+     */
+    showAddViewButtonWhenEmpty?: boolean;
 }
 export interface DashCanvasItemState {
     layout: DashCanvasItemLayout;
@@ -45,7 +70,12 @@ export declare class DashCanvasModel extends DashModel<DashCanvasViewSpec, DashC
     compact: boolean;
     margin: [number, number];
     containerPadding: [number, number];
+    DROPPING_ELEM_ID: string;
     maxRows: number;
+    showAddViewButtonWhenEmpty: boolean;
+    droppable: boolean;
+    onDropDone: (viewModel: DashCanvasViewModel) => void;
+    draggedInView: DashCanvasItemState;
     /** Current number of rows in canvas */
     get rows(): number;
     get isEmpty(): boolean;
@@ -54,7 +84,7 @@ export declare class DashCanvasModel extends DashModel<DashCanvasViewSpec, DashC
     isResizing: boolean;
     private isLoadingState;
     get rglLayout(): any[];
-    constructor({ viewSpecs, viewSpecDefaults, initialState, layoutLocked, contentLocked, renameLocked, persistWith, emptyText, addViewButtonText, columns, rowHeight, compact, margin, maxRows, containerPadding, extraMenuItems }: DashCanvasConfig);
+    constructor({ viewSpecs, viewSpecDefaults, initialState, layoutLocked, contentLocked, renameLocked, persistWith, emptyText, addViewButtonText, columns, rowHeight, compact, margin, maxRows, containerPadding, extraMenuItems, showAddViewButtonWhenEmpty, droppable, onDropDone, onDropDragOver }: DashCanvasConfig);
     /** Removes all views from the canvas */
     clear(): void;
     /**
@@ -92,15 +122,22 @@ export declare class DashCanvasModel extends DashModel<DashCanvasViewSpec, DashC
     renameView(id: string): void;
     /** Scrolls a DashCanvasView into view. */
     ensureViewVisible(id: string): void;
+    onDrop(rglLayout: Layout[], layoutItem: Layout, evt: Event): void;
+    setDraggedInView(view?: DashCanvasItemState): void;
+    onDropDragOver(e: DragOverEvent): {
+        w?: number;
+        h?: number;
+    } | false | undefined;
     getPersistableState(): PersistableState<{
         state: DashCanvasItemState[];
     }>;
     setPersistableState(persistableState: PersistableState<{
         state: DashCanvasItemState[];
     }>): void;
+    private doDrop;
     private getLayoutFromPosition;
     private addViewInternal;
-    onRglLayoutChange(rglLayout: any): void;
+    onRglLayoutChange(rglLayout: Layout[]): void;
     private setLayout;
     private loadState;
     private buildState;

package/desktop/cmp/dash/canvas/DashCanvas.ts

@@ -4,6 +4,12 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
+import ReactGridLayout, {
+    type ReactGridLayoutProps,
+    type DragOverEvent,
+    type Layout,
+    WidthProvider
+} from 'react-grid-layout';
 import {showContextMenu} from '@xh/hoist/kit/blueprint';
 import composeRefs from '@seznam/compose-react-refs';
 import {div, vbox, vspacer} from '@xh/hoist/cmp/layout';
@@ -20,8 +26,6 @@ import '@xh/hoist/desktop/register';
 import {Classes, overlay} from '@xh/hoist/kit/blueprint';
 import {consumeEvent, TEST_ID} from '@xh/hoist/utils/js';
 import classNames from 'classnames';
-import ReactGridLayout, {WidthProvider} from 'react-grid-layout';
-import type {ReactGridLayoutProps} from 'react-grid-layout';
 import {DashCanvasModel} from './DashCanvasModel';
 import {dashCanvasContextMenu} from './impl/DashCanvasContextMenu';
 import {dashCanvasView} from './impl/DashCanvasView';
@@ -87,7 +91,7 @@ export const [DashCanvas, dashCanvas] = hoistCmp.withFactory<DashCanvasProps>({
                         draggableHandle:
                             '.xh-dash-tab.xh-panel > .xh-panel__content > .xh-panel-header',
                         draggableCancel: '.xh-button',
-                        onLayoutChange: layout => model.onRglLayoutChange(layout),
+                        onLayoutChange: (layout: Layout[]) => model.onRglLayoutChange(layout),
                         onResizeStart: () => (model.isResizing = true),
                         onResizeStop: () => (model.isResizing = false),
                         items: model.viewModels.map(vm =>
@@ -96,9 +100,13 @@ export const [DashCanvas, dashCanvas] = hoistCmp.withFactory<DashCanvasProps>({
                                 item: dashCanvasView({model: vm})
                             })
                         ),
+                        isDroppable: model.droppable,
+                        onDrop: (layout: Layout[], layoutItem: Layout, evt: Event) =>
+                            model.onDrop(layout, layoutItem, evt),
+                        onDropDragOver: (evt: DragOverEvent) => model.onDropDragOver(evt),
                         ...rglOptions
                     }),
-                    emptyContainerOverlay()
+                    emptyContainerOverlay({omit: !model.showAddViewButtonWhenEmpty})
                 ],
                 [TEST_ID]: testId
             })

package/desktop/cmp/dash/canvas/DashCanvasModel.ts

@@ -4,6 +4,7 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
+import type {DragOverEvent, Layout} from 'react-grid-layout';
 import {Persistable, PersistableState, PersistenceProvider, XH} from '@xh/hoist/core';
 import {required} from '@xh/hoist/data';
 import {DashCanvasViewModel, DashCanvasViewSpec, DashConfig, DashViewState, DashModel} from '../';
@@ -16,6 +17,7 @@ import {createObservableRef} from '@xh/hoist/utils/react';
 import {
     defaultsDeep,
     find,
+    omit,
     uniqBy,
     times,
     without,
@@ -50,6 +52,31 @@ export interface DashCanvasConfig extends DashConfig<DashCanvasViewSpec, DashCan
 
     /** Padding inside the container [x, y] in pixels. Defaults to same as `margin`. */
     containerPadding?: [number, number];
+
+    /**
+     * Whether the canvas should accept drag-and-drop of views from outside
+     * the canvas. Default false.
+     */
+    droppable?: boolean;
+
+    /**
+     * Optional Callback to invoke after a view is successfully dropped onto the canvas.
+     */
+    onDropDone?: (viewModel: DashCanvasViewModel) => void;
+
+    /**
+     * Optional callback to invoke when an item is dragged over the canvas. This may be used to
+     * customize how the size of the dropping placeholder is calculated. The callback should
+     * return an object with optional 'w' and 'h' properties indicating the desired width and height
+     * (in grid units) of the dropping placeholder. If not provided, Hoist's own default logic will be used.
+     */
+    onDropDragOver?: (e: DragOverEvent) => {w?: number; h?: number} | false | undefined;
+
+    /**
+     * Whether an overlay with an Add View button should be rendered
+     * when the canvas is empty. Default true.
+     */
+    showAddViewButtonWhenEmpty?: boolean;
 }
 
 export interface DashCanvasItemState {
@@ -86,7 +113,12 @@ export class DashCanvasModel
     //-----------------------------
     // Public properties
     //-----------------------------
+    DROPPING_ELEM_ID = '__dropping-elem__';
     maxRows: number;
+    showAddViewButtonWhenEmpty: boolean;
+    droppable: boolean;
+    onDropDone: (viewModel: DashCanvasViewModel) => void;
+    draggedInView: DashCanvasItemState;
 
     /** Current number of rows in canvas */
     get rows(): number {
@@ -106,21 +138,27 @@ export class DashCanvasModel
     private isLoadingState: boolean;
 
     get rglLayout() {
-        return this.layout.map(it => {
-            const dashCanvasView = this.getView(it.i),
-                {autoHeight, viewSpec} = dashCanvasView;
-
-            return {
-                ...it,
-                resizeHandles: autoHeight
-                    ? ['w', 'e']
-                    : ['s', 'w', 'e', 'n', 'sw', 'nw', 'se', 'ne'],
-                maxH: viewSpec.maxHeight,
-                minH: viewSpec.minHeight,
-                maxW: viewSpec.maxWidth,
-                minW: viewSpec.minWidth
-            };
-        });
+        return this.layout
+            .map(it => {
+                const dashCanvasView = this.getView(it.i);
+
+                // `dashCanvasView` will not be found if `it` is a dropping element.
+                if (!dashCanvasView) return null;
+
+                const {autoHeight, viewSpec} = dashCanvasView;
+
+                return {
+                    ...it,
+                    resizeHandles: autoHeight
+                        ? ['w', 'e']
+                        : ['s', 'w', 'e', 'n', 'sw', 'nw', 'se', 'ne'],
+                    maxH: viewSpec.maxHeight,
+                    minH: viewSpec.minHeight,
+                    maxW: viewSpec.maxWidth,
+                    minW: viewSpec.minWidth
+                };
+            })
+            .filter(Boolean);
     }
 
     constructor({
@@ -139,7 +177,11 @@ export class DashCanvasModel
         margin = [10, 10],
         maxRows = Infinity,
         containerPadding = margin,
-        extraMenuItems
+        extraMenuItems,
+        showAddViewButtonWhenEmpty = true,
+        droppable = false,
+        onDropDone,
+        onDropDragOver
     }: DashCanvasConfig) {
         super();
         makeObservable(this);
@@ -187,6 +229,11 @@ export class DashCanvasModel
         this.emptyText = emptyText;
         this.addViewButtonText = addViewButtonText;
         this.extraMenuItems = extraMenuItems;
+        this.showAddViewButtonWhenEmpty = showAddViewButtonWhenEmpty;
+        this.droppable = droppable;
+        this.onDropDone = onDropDone;
+        // Override default onDropDragOver if provided
+        if (onDropDragOver) this.onDropDragOver = onDropDragOver;
 
         this.loadState(initialState);
         this.state = this.buildState();
@@ -312,6 +359,31 @@ export class DashCanvasModel
         this.getView(id)?.ensureVisible();
     }
 
+    onDrop(rglLayout: Layout[], layoutItem: Layout, evt: Event) {
+        throwIf(
+            !this.draggedInView,
+            `No draggedInView set on DashCanvasModel prior to onDrop operation.
+            Typically a developer would set this in response to dragstart events from
+             a DashViewTray or similar component.`
+        );
+
+        const {viewSpecId, title, state} = this.draggedInView,
+            layout = omit(layoutItem, 'i'),
+            newViewModel = this.doDrop(viewSpecId, {title, state, layout}, rglLayout);
+
+        this.draggedInView = null;
+        this.onDropDone?.(newViewModel);
+    }
+
+    setDraggedInView(view?: DashCanvasItemState) {
+        this.draggedInView = view;
+    }
+
+    onDropDragOver(e: DragOverEvent): {w?: number; h?: number} | false | undefined {
+        if (!this.draggedInView) return false;
+        return {w: 6, h: 6};
+    }
+
     //------------------------
     // Persistable Interface
     //------------------------
@@ -327,6 +399,24 @@ export class DashCanvasModel
     //------------------------
     // Implementation
     //------------------------
+    @action
+    private doDrop(
+        specId: string,
+        opts: {
+            title: string;
+            state: any;
+            layout: DashCanvasItemLayout;
+        },
+        rglLayout: Layout[]
+    ): DashCanvasViewModel {
+        const newViewModel: DashCanvasViewModel = this.addViewInternal(specId, opts),
+            droppingItem: any = rglLayout.find(it => it.i === this.DROPPING_ELEM_ID);
+
+        droppingItem.i = newViewModel.id;
+        this.onRglLayoutChange(rglLayout);
+        return newViewModel;
+    }
+
     private getLayoutFromPosition(position: string, specId: string) {
         switch (position) {
             case 'first':
@@ -384,8 +474,14 @@ export class DashCanvasModel
         return model;
     }
 
-    onRglLayoutChange(rglLayout) {
+    onRglLayoutChange(rglLayout: Layout[]) {
         rglLayout = rglLayout.map(it => pick(it, ['i', 'x', 'y', 'w', 'h']));
+
+        // Early out if RGL is changing layout as user is dragging droppable
+        // item around the canvas.  This will be called again once dragging
+        // has stopped and user has dropped the item onto the canvas.
+        if (rglLayout.some(it => it.i === this.DROPPING_ELEM_ID)) return;
+
         this.setLayout(rglLayout);
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "79.0.0-SNAPSHOT.1764947672059",
+  "version": "79.0.0-SNAPSHOT.1764952313480",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",