Merge pull request #3406 from adumesny/master

find drag handles inside open shadow roots

Author: adumesny

demo/title_drag.html

@@ -18,10 +18,26 @@ <h1>Title area drag</h1>
         <div class="card-header">- Drag here -</div>
         <div class="card">the rest of the panel content doesn't drag</div>
       </div></div>
+      <div class="grid-stack-item" gs-x="3" gs-w="3" gs-h="3"><div class="grid-stack-item-content">
+        <my-card></my-card>
+      </div></div>
     </div>
   </div>
   <script src="events.js"></script>
   <script type="text/javascript">
+    class MyCard extends HTMLElement {
+      constructor() {
+        super();
+        const shadow = this.attachShadow({mode: 'open'});
+        shadow.innerHTML = `
+          <link rel="stylesheet" href="demo.css"/>
+          <div class="card-header">- Web Component Drag -</div>
+          <div class="card" style="padding: 8px">Shadow DOM content doesn't drag</div>
+        `;
+      }
+    }
+    customElements.define('my-card', MyCard);
+
     let grid = GridStack.init({ handle: '.card-header' }); // drag by the header only
     addEvents(grid);
   </script>

doc/API.md

@@ -430,7 +430,7 @@ Destroys a grid instance. DO NOT CALL any methods or access any vars after this
 disable(recurse): GridStack;
 ```
 
-Defined in: [gridstack.ts:2430](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2430)
+Defined in: [gridstack.ts:2443](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2443)
 
 Temporarily disables widgets moving/resizing.
 If you want a more permanent way (which freezes up resources) use `setStatic(true)` instead.
@@ -471,7 +471,7 @@ grid.disable(false);
 enable(recurse): GridStack;
 ```
 
-Defined in: [gridstack.ts:2457](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2457)
+Defined in: [gridstack.ts:2470](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2470)
 
 Re-enables widgets moving/resizing - see disable().
 Note: This is a no-op for static grids.
@@ -510,7 +510,7 @@ grid.enable(false);
 enableMove(doEnable, recurse): GridStack;
 ```
 
-Defined in: [gridstack.ts:2483](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2483)
+Defined in: [gridstack.ts:2496](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2496)
 
 Enables/disables widget moving for all widgets. No-op for static grids.
 Note: locally defined items (with noMove property) still override this setting.
@@ -547,7 +547,7 @@ grid.enableMove(true, false);
 enableResize(doEnable, recurse): GridStack;
 ```
 
-Defined in: [gridstack.ts:2511](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2511)
+Defined in: [gridstack.ts:2524](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2524)
 
 Enables/disables widget resizing for all widgets. No-op for static grids.
 Note: locally defined items (with noResize property) still override this setting.
@@ -1098,7 +1098,7 @@ grid.mode('list');  // continuous sequential reflow, like a re-orderable list
 movable(els, val): GridStack;
 ```
 
-Defined in: [gridstack.ts:2371](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2371)
+Defined in: [gridstack.ts:2384](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2384)
 
 Enables/Disables dragging by the user for specific grid elements.
 For all items and future items, use enableMove() instead. No-op for static grids.
@@ -1457,7 +1457,7 @@ or `sizeToContent` gridItem options.
 prepareDragDrop(el, force?): GridStack;
 ```
 
-Defined in: [gridstack.ts:2900](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2900)
+Defined in: [gridstack.ts:2913](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2913)
 
 prepares the element for drag&drop - this is normally called by makeWidget() unless are are delay loading
 
@@ -1478,7 +1478,7 @@ prepares the element for drag&drop - this is normally called by makeWidget() unl
 refreshDragHandles(els): GridStack;
 ```
 
-Defined in: [gridstack.ts:2888](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2888)
+Defined in: [gridstack.ts:2901](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2901)
 
 Re-scans one or more widget elements for drag handle elements after delayed content
 (React portal, Angular component, etc.) has been rendered inside the item.
@@ -1599,7 +1599,7 @@ Removes widget from the grid.
 resizable(els, val): GridStack;
 ```
 
-Defined in: [gridstack.ts:2397](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2397)
+Defined in: [gridstack.ts:2410](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L2410)
 
 Enables/Disables user resizing for specific grid elements.
 For all items and future items, use enableResize() instead. No-op for static grids.
@@ -1811,7 +1811,7 @@ is dynamically create and needs to be set later.
 protected triggerEvent(event, target): void;
 ```
 
-Defined in: [gridstack.ts:3162](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L3162)
+Defined in: [gridstack.ts:3175](https://github.com/adumesny/gridstack.js/blob/master/src/gridstack.ts#L3175)
 
 call given event callback on our main top-most grid (if we're nested)
 
@@ -4094,7 +4094,7 @@ Defined in: [dd-draggable.ts:70](https://github.com/adumesny/gridstack.js/blob/m
 destroy(): void;
 ```
 
-Defined in: [dd-draggable.ts:135](https://github.com/adumesny/gridstack.js/blob/master/src/dd-draggable.ts#L135)
+Defined in: [dd-draggable.ts:154](https://github.com/adumesny/gridstack.js/blob/master/src/dd-draggable.ts#L154)
 
 Destroy this drag & drop implementation and clean up resources.
 Removes all event handlers and clears internal state.
@@ -4113,7 +4113,7 @@ Removes all event handlers and clears internal state.
 disable(forDestroy): void;
 ```
 
-Defined in: [dd-draggable.ts:121](https://github.com/adumesny/gridstack.js/blob/master/src/dd-draggable.ts#L121)
+Defined in: [dd-draggable.ts:140](https://github.com/adumesny/gridstack.js/blob/master/src/dd-draggable.ts#L140)
 
 Disable this drag & drop implementation.
 Subclasses should override to perform additional cleanup.
@@ -4138,7 +4138,7 @@ Subclasses should override to perform additional cleanup.
 enable(): void;
 ```
 
-Defined in: [dd-draggable.ts:107](https://github.com/adumesny/gridstack.js/blob/master/src/dd-draggable.ts#L107)
+Defined in: [dd-draggable.ts:126](https://github.com/adumesny/gridstack.js/blob/master/src/dd-draggable.ts#L126)
 
 Enable this drag & drop implementation.
 Subclasses should override to perform additional setup.
@@ -4171,7 +4171,7 @@ return all handles omitting other nested `.grid-stack-item` children (in case no
 off(event): void;
 ```
 
-Defined in: [dd-draggable.ts:103](https://github.com/adumesny/gridstack.js/blob/master/src/dd-draggable.ts#L103)
+Defined in: [dd-draggable.ts:122](https://github.com/adumesny/gridstack.js/blob/master/src/dd-draggable.ts#L122)
 
 Unregister an event callback for the specified event.
 
@@ -4195,7 +4195,7 @@ Unregister an event callback for the specified event.
 on(event, callback): void;
 ```
 
-Defined in: [dd-draggable.ts:99](https://github.com/adumesny/gridstack.js/blob/master/src/dd-draggable.ts#L99)
+Defined in: [dd-draggable.ts:118](https://github.com/adumesny/gridstack.js/blob/master/src/dd-draggable.ts#L118)
 
 Register an event callback for the specified event.
 
@@ -4220,7 +4220,7 @@ Register an event callback for the specified event.
 refreshHandles(): void;
 ```
 
-Defined in: [dd-draggable.ts:156](https://github.com/adumesny/gridstack.js/blob/master/src/dd-draggable.ts#L156)
+Defined in: [dd-draggable.ts:175](https://github.com/adumesny/gridstack.js/blob/master/src/dd-draggable.ts#L175)
 
 Re-scans the item element for drag-handle elements after delayed content (React portal,
 Angular component, etc.) has been rendered into the item.  Removes listeners from the
@@ -4264,7 +4264,7 @@ Result from the callback function, if any
 updateOption(opts): DDDraggable;
 ```
 
-Defined in: [dd-draggable.ts:145](https://github.com/adumesny/gridstack.js/blob/master/src/dd-draggable.ts#L145)
+Defined in: [dd-draggable.ts:164](https://github.com/adumesny/gridstack.js/blob/master/src/dd-draggable.ts#L164)
 
 Method to update the options and return the DD implementation
 

doc/CHANGES.md

@@ -155,6 +155,8 @@ Change log
 * feat: [#2627](https://github.com/gridstack/gridstack.js/issues/2627), [#2761](https://github.com/gridstack/gridstack.js/issues/2761) emit dragstart/drag/dragstop on sidebar drag-in items
 * fix: [#3012](https://github.com/gridstack/gridstack.js/issues/3012), [#3179](https://github.com/gridstack/gridstack.js/issues/3179) prevent crash when calling update() during change event
 * fix: [#3226](https://github.com/gridstack/gridstack.js/issues/3226) don't reveal other widgets' resize handles during a resize - thank you [dvd233](https://github.com/dvd233)
+* fix: [#3148](https://github.com/gridstack/gridstack.js/issues/3148) find drag handles inside open shadow roots. See
+[title_drag.html](https://gridstackjs.com/demo/title_drag.html).
 
 ## 13.3.0 (2026-09-11)
 * feat: [#2781](https://github.com/gridstack/gridstack.js/issues/3177), [#2781](https://github.com/gridstack/gridstack.js/issues/3177) mobile: pause to drag/reszie vs scroll behavior

spec/regression-spec.ts

@@ -2,6 +2,7 @@ import { GridItemHTMLElement, GridStack, GridStackWidget } from '../src/gridstac
 import type { GridStackNode } from '../src/types';
 import { Utils } from '../src/utils';
 import { DDManager } from '../src/dd-manager';
+import { DDElement } from '../src/dd-element';
 
 describe('regression >', () => {
   'use strict';
@@ -514,4 +515,62 @@ describe('regression >', () => {
       expect(detail?.ui).toBeDefined();
     });
   });
+
+  describe('3148 drag handle inside a shadow root >', () => {
+    let host: GridItemHTMLElement;
+    afterEach(() => {
+      delete DDManager.mouseHandled;
+      host?.remove();
+    });
+
+    /** a card whose drag handle lives inside a web component's shadow root */
+    const build = () => {
+      document.body.insertAdjacentHTML('afterbegin',
+        '<div class="grid-stack-item"><div class="grid-stack-item-content">' +
+        '<div class="card"></div></div></div>');
+      host = document.querySelector('.grid-stack-item') as GridItemHTMLElement;
+      const card = host.querySelector('.card') as HTMLElement;
+      const shadow = card.attachShadow({mode: 'open'});
+      shadow.innerHTML = '<button class="drag-handle">::</button><div class="body">scroll me</div>';
+      const dd = DDElement.init(host).setupDraggable({handle: '.drag-handle'}).ddDraggable!;
+      return { dd, shadow };
+    };
+
+    it('finds it, instead of falling back to the whole card', () => {
+      const { dd, shadow } = build();
+      const handle = shadow.querySelector('.drag-handle') as HTMLElement;
+      // querySelectorAll() stops at the shadow boundary, so this used to come back empty and
+      // dragEls fell back to [the whole item] - the entire card stayed draggable
+      expect(dd['dragEls']).toEqual([handle]);
+      expect(dd['dragEls']).not.toContain(host);
+    });
+
+    it('only the handle starts a drag, so the rest can still scroll', () => {
+      const { dd, shadow } = build();
+      const started = (target: HTMLElement): boolean => {
+        target.dispatchEvent(new MouseEvent('mousedown', {button: 0, bubbles: true, composed: true}));
+        const ok = !!dd['mouseDownEvent'];
+        dd['_mouseUp'](new MouseEvent('mouseup'));
+        delete DDManager.mouseHandled;
+        return ok;
+      };
+      expect(started(shadow.querySelector('.drag-handle') as HTMLElement)).toBe(true);
+      expect(started(shadow.querySelector('.body') as HTMLElement)).toBe(false);
+    });
+
+    it("does not steal a nested item's handle", () => {
+      document.body.insertAdjacentHTML('afterbegin',
+        '<div class="grid-stack-item outer"><div class="grid-stack-item-content">' +
+        '<div class="grid-stack"><div class="grid-stack-item inner">' +
+        '<div class="grid-stack-item-content"><div class="card"></div></div>' +
+        '</div></div></div></div>');
+      host = document.querySelector('.outer') as GridItemHTMLElement;
+      const card = host.querySelector('.card') as HTMLElement;
+      const shadow = card.attachShadow({mode: 'open'});
+      shadow.innerHTML = '<button class="drag-handle">::</button>';
+      const dd = DDElement.init(host).setupDraggable({handle: '.drag-handle'}).ddDraggable!;
+      // that handle belongs to .inner (through the shadow host), not to us
+      expect(dd['dragEls']).toEqual([host]); // fell back to ourself, correctly
+    });
+  });
 });

src/dd-draggable.ts

@@ -89,9 +89,28 @@ export class DDDraggable extends DDBaseImplement implements HTMLElementExtendOpt
   protected getAllHandles(): HTMLElement[] {
     const handle = this.option.handle;
     if (!handle) return []; // caller falls back to the item itself
-    return Array.from(this.el.querySelectorAll(handle)).filter((node): node is HTMLElement => {
+    const found: Element[] = [];
+    // querySelectorAll() stops dead at a shadow boundary, so a handle living inside a web component
+    // could never be found and the whole card stayed draggable (#3148). Descend into open shadow
+    // roots too - closed ones are not reachable by design.
+    const scan = (root: Element | ShadowRoot): void => {
+      found.push(...Array.from(root.querySelectorAll(handle)));
+      root.querySelectorAll('*').forEach(child => {
+        const shadow = (child as HTMLElement).shadowRoot;
+        if (shadow) scan(shadow);
+      });
+    };
+    scan(this.el);
+    return found.filter((node): node is HTMLElement => {
       if (!(node instanceof HTMLElement)) return false;
-      const owner = node.closest('.grid-stack-item');
+      // a handle inside a shadow root has no light-DOM .grid-stack-item ancestor to check against,
+      // so walk out through the host(s) to find who really owns it
+      let owner: Element | null = node.closest('.grid-stack-item');
+      let root = node.getRootNode();
+      while (!owner && root instanceof ShadowRoot) {
+        owner = root.host.closest('.grid-stack-item');
+        root = root.host.getRootNode();
+      }
       return owner === this.el || !owner;
     });
   }