@xh/hoist 80.0.0-SNAPSHOT.1767647247785 → 80.0.0-SNAPSHOT.1767973504648

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

@@ -4,6 +4,7 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
+import {wait} from '@xh/hoist/promise';
 import type {LayoutItem} from 'react-grid-layout';
 import {Persistable, PersistableState, PersistenceProvider, XH} from '@xh/hoist/core';
 import {required} from '@xh/hoist/data';
@@ -17,6 +18,7 @@ import {createObservableRef} from '@xh/hoist/utils/react';
 import {
     defaultsDeep,
     find,
+    omit,
     uniqBy,
     times,
     without,
@@ -41,11 +43,12 @@ export interface DashCanvasConfig extends DashConfig<DashCanvasViewSpec, DashCan
     rowHeight?: number;
 
     /**
-     * Whether views should "compact" vertically or horizontally
+     * Whether views should "compact" vertically, horizontally or wrap
      * to condense space. Default `true` defaults to vertical compaction.
+     * Use `wrap` with caution.  It only works well if all items are 1 row high.
      * See react-grid-layout docs for more information.
-     * */
-    compact?: boolean | 'vertical' | 'horizontal';
+     */
+    compact?: boolean | 'vertical' | 'horizontal' | 'wrap';
 
     /** Between items [x,y] in pixels. Default `[10, 10]`. */
     margin?: [number, number];
@@ -60,6 +63,35 @@ export interface DashCanvasConfig extends DashConfig<DashCanvasViewSpec, DashCan
      * Whether a grid background should be shown. Default false.
      */
     showGridBackground?: boolean;
+
+    /**
+     * Whether the canvas should accept drag-and-drop of views from outside
+     * the canvas. Default false.
+     */
+    allowsDrop?: 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 properties indicating the desired width, height (in grid units),
+     * and offset (in pixels) of the dropping placeholder.  The method's signature is the same as
+     * the `onDropDragOver` prop of ReactGridLayout.
+     * Returning `false` will prevent the dropping placeholder from being shown, and prevents a drop.
+     * Returning `void` will use the default behavior, which is to size the placeholder as per the
+     * `dropConfig.defaultItem` specification.
+     */
+    onDropDragOver?: (e: DragEvent) => OnDropDragOverResult;
+
+    /**
+     * Whether an overlay with an Add View button should be rendered
+     * when the canvas is empty. Default true.
+     */
+    showAddViewButtonWhenEmpty?: boolean;
 }
 
 export interface DashCanvasItemState {
@@ -76,6 +108,16 @@ export interface DashCanvasItemLayout {
     h: number;
 }
 
+export type OnDropDragOverResult =
+    | {
+          w?: number;
+          h?: number;
+          dragOffsetX?: number;
+          dragOffsetY?: number;
+      }
+    | false
+    | void;
+
 /**
  * Model for {@link DashCanvas}, managing all configurable options for the component and publishing
  * the observable state of its current widgets and their layout.
@@ -89,16 +131,21 @@ export class DashCanvasModel
     //------------------------------
     @bindable columns: number;
     @bindable rowHeight: number;
-    @bindable compact: 'vertical' | 'horizontal';
+    @bindable compact: 'vertical' | 'horizontal' | 'wrap';
     @bindable.ref margin: [number, number]; // [x, y]
     @bindable.ref containerPadding: [number, number]; // [x, y]
     @bindable showGridBackground: boolean;
     @bindable rglHeight: number;
+    @bindable showAddViewButtonWhenEmpty: boolean;
 
     //-----------------------------
     // Public properties
     //-----------------------------
+    DROPPING_ELEM_ID = '__dropping-elem__';
     maxRows: number;
+    allowsDrop: boolean;
+    onDropDone: (viewModel: DashCanvasViewModel) => void;
+    draggedInView: DashCanvasItemState;
 
     /** Current number of rows in canvas */
     get rows(): number {
@@ -118,21 +165,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({
@@ -152,7 +205,11 @@ export class DashCanvasModel
         maxRows = Infinity,
         containerPadding = margin,
         extraMenuItems,
-        showGridBackground = false
+        showGridBackground = false,
+        showAddViewButtonWhenEmpty = true,
+        allowsDrop = false,
+        onDropDone,
+        onDropDragOver
     }: DashCanvasConfig) {
         super();
         makeObservable(this);
@@ -200,6 +257,10 @@ export class DashCanvasModel
         this.addViewButtonText = addViewButtonText;
         this.extraMenuItems = extraMenuItems;
         this.showGridBackground = showGridBackground;
+        this.showAddViewButtonWhenEmpty = showAddViewButtonWhenEmpty;
+        this.allowsDrop = allowsDrop;
+        this.onDropDone = onDropDone;
+        if (onDropDragOver) this.onDropDragOver = onDropDragOver;
 
         this.loadState(initialState);
         this.state = this.buildState();
@@ -337,6 +398,59 @@ export class DashCanvasModel
         this.getView(id)?.ensureVisible();
     }
 
+    onDrop(rglLayout: LayoutItem[], layoutItem: LayoutItem, 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 droppingItem: any = rglLayout.find(it => it.i === this.DROPPING_ELEM_ID);
+        if (!droppingItem) {
+            // if `onDropDragOver` returned false, we won't have a dropping item
+            // and we cancel the drop
+            this.draggedInView = null;
+            return;
+        }
+
+        const {viewSpecId, title, state} = this.draggedInView,
+            layout = omit(layoutItem, 'i'),
+            newViewModel: DashCanvasViewModel = this.addViewInternal(viewSpecId, {
+                title,
+                state,
+                layout
+            });
+
+        // Change ID of dropping item to the new view's id
+        // so that the new view goes where the dropping item is.
+        droppingItem.i = newViewModel.id;
+
+        // must wait a tick for RGL to settle
+        wait().then(() => {
+            this.draggedInView = null;
+            this.onRglLayoutChange(rglLayout);
+            this.onDropDone?.(newViewModel);
+        });
+    }
+
+    setDraggedInView(view?: DashCanvasItemState) {
+        this.draggedInView = view;
+    }
+
+    onDropDragOver(evt: DragEvent): OnDropDragOverResult {
+        if (!this.draggedInView) return false;
+
+        return {
+            w: this.draggedInView.layout.w,
+            h: this.draggedInView.layout.h
+        };
+    }
+
+    getViewsBySpecId(id) {
+        return this.viewModels.filter(it => it.viewSpec.id === id);
+    }
+
     //------------------------
     // Persistable Interface
     //------------------------
@@ -413,6 +527,12 @@ export class DashCanvasModel
 
     onRglLayoutChange(rglLayout: LayoutItem[]) {
         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);
     }
 
@@ -496,10 +616,6 @@ export class DashCanvasModel
         return some(this.viewSpecs, {id});
     }
 
-    private getViewsBySpecId(id) {
-        return this.viewModels.filter(it => it.viewSpec.id === id);
-    }
-
     private getNextAvailablePosition({
         width,
         height,

package/desktop/cmp/dash/canvas/widgetwell/DashCanvasWidgetWell.scss

@@ -0,0 +1,26 @@
+.xh-dash-canvas-widget-well {
+  padding: 0 var(--xh-pad-px);
+
+  .xh-collapsible-fieldset {
+    margin: var(--xh-pad-half-px) 0;
+  }
+
+  .xh-dash-canvas-draggable-widget {
+    border: var(--xh-border-dotted);
+    background-color: var(--xh-bg-alt);
+    padding: var(--xh-pad-half-px);
+    margin: var(--xh-pad-half-px) 0;
+    cursor: grab;
+
+    &.is-dragging {
+      cursor: grabbing;
+      // lighten background color of left behind placeholder
+      // when dragging
+      opacity: 0.25;
+    }
+
+    &:active {
+      cursor: grabbing;
+    }
+  }
+}

package/desktop/cmp/dash/canvas/widgetwell/DashCanvasWidgetWell.ts

@@ -0,0 +1,126 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2025 Extremely Heavy Industries Inc.
+ */
+
+import {uniqBy} from 'lodash';
+import classNames from 'classnames';
+import type {ReactElement} from 'react';
+import {div, vframe} from '@xh/hoist/cmp/layout';
+import {creates, hoistCmp, HoistProps, uses} from '@xh/hoist/core';
+import {DashCanvasModel, DashCanvasViewSpec} from '@xh/hoist/desktop/cmp/dash';
+import {DashCanvasWidgetWellModel} from '@xh/hoist/desktop/cmp/dash/canvas/widgetwell/DashCanvasWidgetWellModel';
+import {collapsibleFieldset} from '@xh/hoist/desktop/cmp/form/CollapsibleFieldset';
+
+import './DashCanvasWidgetWell.scss';
+
+export interface DashCanvasWidgetWellProps extends HoistProps {
+    /** DashCanvasModel for which this widget well should allow the user to add views from. */
+    dashCanvasModel?: DashCanvasModel;
+}
+
+/**
+ * Widget Well from which to add items to a DashCanvas by drag-and-drop.
+ *
+ * Available view specs are listed in their defined order,
+ * grouped by their 'groupName' property if present.
+ *
+ * Typically, an app developer would place this inside a collapsible panel to the side of
+ * a DashCanvas.
+ */
+export const [DashCanvasWidgetWell, dashCanvasWidgetWell] =
+    hoistCmp.withFactory<DashCanvasWidgetWellProps>({
+        displayName: 'DashCanvasWidgetWell',
+        model: creates(DashCanvasWidgetWellModel),
+        className: 'xh-dash-canvas-widget-well',
+        render({dashCanvasModel, className}) {
+            if (!dashCanvasModel) return;
+
+            return vframe({
+                className: classNames(className),
+                overflow: 'auto',
+                items: createDraggableItems(dashCanvasModel)
+            });
+        }
+    });
+
+//---------------------------
+// Implementation
+//---------------------------
+const draggableWidget = hoistCmp.factory<DashCanvasWidgetWellModel>({
+    displayName: 'DraggableWidget',
+    model: uses(DashCanvasWidgetWellModel),
+    render({model, viewSpec}) {
+        const {id, icon, title} = viewSpec as DashCanvasViewSpec;
+        return div({
+            id: `draggableFor-${id}`,
+            className: 'xh-dash-canvas-draggable-widget',
+            draggable: true,
+            unselectable: 'on',
+            onDragStart: e => model.onDragStart(e),
+            onDragEnd: e => model.onDragEnd(e),
+            items: [icon, ' ', title]
+        });
+    }
+});
+
+/**
+ * Used to create draggable items (for adding views)
+ * @internal
+ */
+function createDraggableItems(dashCanvasModel: DashCanvasModel): any[] {
+    if (!dashCanvasModel.ref.current) return [];
+
+    const groupedItems = {},
+        ungroupedItems = [];
+
+    const addToGroup = (item, icon, groupName) => {
+        const group = groupedItems[groupName];
+        if (group) {
+            group.push({item, icon});
+        } else {
+            groupedItems[groupName] = [{item, icon}];
+        }
+    };
+
+    dashCanvasModel.viewSpecs
+        .filter(viewSpec => {
+            return (
+                viewSpec.allowAdd &&
+                (!viewSpec.unique || !dashCanvasModel.getViewsBySpecId(viewSpec.id).length)
+            );
+        })
+        .forEach(viewSpec => {
+            const {groupName} = viewSpec,
+                item = draggableWidget({viewSpec});
+
+            if (groupName) {
+                addToGroup(item, viewSpec.icon, groupName);
+            } else {
+                ungroupedItems.push(item);
+            }
+        });
+
+    return [
+        ...Object.keys(groupedItems).map(group => {
+            const label = group,
+                items = groupedItems[group],
+                sameIcons =
+                    uniqBy<{item: ReactElement; icon: ReactElement}>(
+                        items,
+                        it => it.icon.props.iconName
+                    ).length === 1,
+                icon = sameIcons ? items[0].icon : null;
+
+            return collapsibleFieldset({
+                icon,
+                collapsed: false,
+                label,
+                items: items.map(it => it.item)
+            });
+        }),
+        ...ungroupedItems
+    ];
+}

package/desktop/cmp/dash/canvas/widgetwell/DashCanvasWidgetWellModel.ts

@@ -0,0 +1,65 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2025 Extremely Heavy Industries Inc.
+ */
+import {DragEvent} from 'react';
+import {DashCanvasModel} from '@xh/hoist/desktop/cmp/dash';
+import {HoistModel, managed} from '@xh/hoist/core';
+import '@xh/hoist/desktop/register';
+import {makeObservable, observable} from '@xh/hoist/mobx';
+import {runInAction} from 'mobx';
+
+export class DashCanvasWidgetWellModel extends HoistModel {
+    @managed
+    @observable.ref
+    dashCanvasModel: DashCanvasModel;
+
+    constructor() {
+        super();
+        makeObservable(this);
+    }
+
+    override onLinked() {
+        this.addReaction({
+            track: () => this.componentProps,
+            run: () =>
+                runInAction(() => (this.dashCanvasModel = this.componentProps.dashCanvasModel)),
+            fireImmediately: true
+        });
+    }
+
+    onDragStart(evt: DragEvent<HTMLDivElement>) {
+        const target = evt.target as HTMLElement;
+        if (!target) return;
+
+        this.dashCanvasModel.showAddViewButtonWhenEmpty = false;
+        evt.dataTransfer.effectAllowed = 'move';
+        target.classList.add('is-dragging');
+
+        const viewSpecId: string = target.getAttribute('id').split('draggableFor-')[1],
+            viewSpec = this.dashCanvasModel.viewSpecs.find(it => it.id === viewSpecId),
+            {width, height} = viewSpec,
+            widget = {
+                viewSpecId,
+                layout: {
+                    x: 0,
+                    y: 0,
+                    w: width,
+                    h: height
+                }
+            };
+
+        this.dashCanvasModel.setDraggedInView(widget);
+    }
+
+    onDragEnd(evt: DragEvent<HTMLDivElement>) {
+        this.dashCanvasModel.showAddViewButtonWhenEmpty = true;
+
+        const target = evt.target as HTMLElement;
+        if (!target) return;
+
+        target.classList.remove('is-dragging');
+    }
+}

package/desktop/cmp/form/CollapsibleFieldset.scss

@@ -0,0 +1,14 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2026 Extremely Heavy Industries Inc.
+ */
+
+.xh-collapsible-fieldset {
+  &--collapsed {
+    border-bottom: none;
+    border-left: none;
+    border-right: none;
+  }
+}

package/desktop/cmp/form/CollapsibleFieldset.ts

@@ -0,0 +1,65 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2026 Extremely Heavy Industries Inc.
+ */
+
+import {fieldsetCollapseButton} from '@xh/hoist/desktop/cmp/button/FieldsetCollapseButton';
+import classNames from 'classnames';
+import {castArray} from 'lodash';
+import {type FieldsetHTMLAttributes, type ReactElement, type ReactNode, useState} from 'react';
+import {hoistCmp, HoistProps} from '@xh/hoist/core';
+import {fieldset} from '@xh/hoist/cmp/layout';
+
+import './CollapsibleFieldset.scss';
+
+export interface CollapsibleFieldsetProps
+    extends FieldsetHTMLAttributes<HTMLFieldSetElement>, HoistProps {
+    icon?: ReactElement;
+    label: ReactNode;
+    clickHandler?: () => void;
+    collapsed?: boolean;
+    hideItemCount?: boolean;
+}
+
+export const [CollapsibleFieldset, collapsibleFieldset] =
+    hoistCmp.withFactory<CollapsibleFieldsetProps>({
+        displayName: 'FieldsetCollapseButton',
+        model: false,
+        className: 'xh-collapsible-fieldset',
+        render({icon, label, collapsed, children, hideItemCount, className, disabled, ...rest}) {
+            const [isCollapsed, setIsCollapsed] = useState<boolean>(collapsed === true),
+                items = castArray(children),
+                itemCount = hideItemCount === true ? '' : ` (${items.length})`,
+                classes = [];
+
+            if (isCollapsed) {
+                classes.push('xh-collapsible-fieldset--collapsed');
+            } else {
+                classes.push('xh-collapsible-fieldset--expanded');
+            }
+
+            if (disabled) {
+                classes.push('xh-collapsible-fieldset--disabled');
+            } else {
+                classes.push('xh-collapsible-fieldset--enabled');
+            }
+
+            return fieldset({
+                className: classNames(className, classes),
+                items: [
+                    fieldsetCollapseButton({
+                        icon,
+                        text: `${label}${itemCount}`,
+                        clickHandler: val => setIsCollapsed(val),
+                        collapsed: isCollapsed,
+                        disabled
+                    }),
+                    ...(isCollapsed ? [] : items)
+                ],
+                disabled,
+                ...rest
+            });
+        }
+    });

package/desktop/cmp/viewmanager/ViewManager.ts

@@ -86,7 +86,7 @@ export const [ViewManager, viewManager] = hoistCmp.withFactory<ViewManagerProps>
         buttonSide = 'right',
         extraMenuItems = []
     }: ViewManagerProps) {
-        const {loadModel} = model,
+        const {loadObserver} = model,
             locModel = useLocalModel(() => new ViewManagerLocalModel(model)),
             save = saveButton({model: locModel, mode: showSaveButton, ...saveButtonProps}),
             revert = revertButton({model: locModel, mode: showRevertButton, ...revertButtonProps}),
@@ -103,7 +103,7 @@ export const [ViewManager, viewManager] = hoistCmp.withFactory<ViewManagerProps>
                     }),
                     ...menuButtonProps
                 }),
-                content: loadModel.isPending
+                content: loadObserver.isPending
                     ? box({
                           item: spinner({compact: true}),
                           alignItems: 'center',

package/mobile/appcontainer/AppContainer.ts

@@ -143,7 +143,7 @@ const appContainerView = hoistCmp.factory<AppContainerModel>({
 });
 
 const appLoadMask = hoistCmp.factory<AppContainerModel>(({model}) =>
-    mask({bind: model.appLoadModel, spinner: true})
+    mask({bind: model.appLoadObserver, spinner: true})
 );
 
 const bannerList = hoistCmp.factory<AppContainerModel>({

package/mobile/appcontainer/LoginPanel.ts

@@ -26,7 +26,7 @@ export const loginPanel = hoistCmp.factory({
 
     render({model}) {
         const {loginMessage} = XH.appSpec,
-            {isValid, loadModel, warning, loginInProgress} = model;
+            {isValid, loadObserver, warning, loginInProgress} = model;
 
         return panel({
             className: 'xh-login',
@@ -34,7 +34,7 @@ export const loginPanel = hoistCmp.factory({
                 toolbar(filler(), XH.clientAppName, filler()),
                 panel({
                     className: 'xh-login__body',
-                    mask: loadModel,
+                    mask: loadObserver,
                     items: [
                         form({
                             className: 'xh-login__fields',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "80.0.0-SNAPSHOT.1767647247785",
+  "version": "80.0.0-SNAPSHOT.1767973504648",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",
@@ -62,11 +62,11 @@
     "moment": "~2.30.1",
     "numbro": "~2.5.0",
     "onsenui": "~2.12.8",
-    "qs": "~6.14.0",
+    "qs": "~6.14.1",
     "react-beautiful-dnd": "~13.1.0",
     "react-dates": "~21.8.0",
     "react-dropzone": "~10.2.2",
-    "react-grid-layout": "2.1.1",
+    "react-grid-layout": "2.2.2",
     "react-markdown": "~10.1.0",
     "react-onsenui": "~1.13.2",
     "react-popper": "~2.3.0",