setupDragIn() signature fix

* set root: HTMLElement | Document so either can be passed now
more fix #2275

Author: adumesny

doc/CHANGES.md

@@ -88,6 +88,7 @@ Change log
 ## 8.0.2 TBD
 * break: remove `GridStackOptions.minWidth` obsolete since 5.1, use `oneColumnSize` instead
 * optimize: CSS files now even 25% smaller (after being halfed in 8.0.0) by removing `.grid-stack` prefix for anything already gs based, and 3 digit rounding.
+* fix: [#2275](https://github.com/gridstack/gridstack.js/issues/2275) `setupDragIn()` signature tweaks (HTMLElement | Document)
 
 ## 8.0.1 (2023-04-29)
 * feat: [#2275](https://github.com/gridstack/gridstack.js/issues/2275) `setupDragIn()` now can take an array or elements (in addition to selector string) and optional parent root (for shadow DOM support)

doc/README.md

@@ -28,7 +28,7 @@ gridstack.js API
   - [`init(options: GridStackOptions = {}, elOrString: GridStackElement = '.grid-stack'): GridStack`](#initoptions-gridstackoptions---elorstring-gridstackelement--grid-stack-gridstack)
   - [`initAll(options: GridStackOptions = {}, selector = '.grid-stack'): GridStack[]`](#initalloptions-gridstackoptions---selector--grid-stack-gridstack)
   - [`addGrid(parent: HTMLElement, opt: GridStackOptions = {}): GridStack `](#addgridparent-htmlelement-opt-gridstackoptions---gridstack-)
-  - [`setupDragIn(dragIn?: string | HTMLElement[], dragInOptions?: DDDragInOpt, root = document)`](#setupdragindragin-string--htmlelement-draginoptions-dddraginopt-root--document)
+  - [`setupDragIn(dragIn?: string | HTMLElement[], dragInOptions?: DDDragInOpt, root = HTMLElement | Document)`](#setupdragindragin-string--htmlelement-draginoptions-dddraginopt-root--htmlelement--document)
   - [`GridStack.registerEngine(engineClass: typeof GridStackEngine)`](#gridstackregisterengineengineclass-typeof-gridstackengine)
 - [API](#api)
   - [`addWidget(el?: GridStackWidget | GridStackElement, options?: GridStackWidget)`](#addwidgetel-gridstackwidget--gridstackelement-options-gridstackwidget)
@@ -323,13 +323,13 @@ grids.forEach(...)
 * @param opt grids options used to initialize the grid, and list of children
 * see [nested.html](https://github.com/gridstack/gridstack.js/tree/master/demo/nested.html) demo
 
-### `setupDragIn(dragIn?: string | HTMLElement[], dragInOptions?: DDDragInOpt, root = document)`
+### `setupDragIn(dragIn?: string | HTMLElement[], dragInOptions?: DDDragInOpt, root = HTMLElement | Document)`
 
 * call to setup dragging in from the outside (say toolbar), by specifying the class selection and options.
 Called during `GridStack.init()` as options, but can also be called directly (last param are cached) in case the toolbar is dynamically create and needs to change later.
 * @param dragIn string selector (ex: `'.sidebar .grid-stack-item'`) or list of dom elements
 * @param dragInOptions options - see `DDDragInOpt`. (default: `{handle: '.grid-stack-item-content', appendTo: 'body'}`
-* @param root - default to document (for shadow dom support)
+* @param root - default to document. for shadow dom support pass the parent container.
 but you will probably also want `helper: 'clone'` or your own callback function).
 
 ### `GridStack.registerEngine(engineClass: typeof GridStackEngine)`

src/gridstack.ts

@@ -1660,9 +1660,9 @@ export class GridStack {
    * is dynamically create and needs to be set later.
    * @param dragIn string selector (ex: '.sidebar .grid-stack-item') or list of dom elements
    * @param dragInOptions options - see DDDragInOpt. (default: {handle: '.grid-stack-item-content', appendTo: 'body'}
-   * @param root optional root which defaults to document (for shadow dom)
+   * @param root optional root which defaults to document (for shadow dom pas the parent HTMLDocument)
    **/
-  public static setupDragIn(dragIn?: string | HTMLElement[], dragInOptions?: DDDragInOpt, root = document): void {
+  public static setupDragIn(dragIn?: string | HTMLElement[], dragInOptions?: DDDragInOpt, root: HTMLElement | Document = document): void {
     if (dragInOptions?.pause !== undefined) {
       DDManager.pauseDrag = dragInOptions.pause;
     }

src/utils.ts

@@ -54,14 +54,15 @@ export function obsoleteAttr(el: HTMLElement, oldName: string, newName: string,
 export class Utils {
 
   /** convert a potential selector into actual list of html elements. optional root which defaults to document (for shadow dom) */
-  static getElements(els: GridStackElement, root = document): HTMLElement[] {
+  static getElements(els: GridStackElement, root: HTMLElement | Document = document): HTMLElement[] {
+    const doc = ('getElementById' in root) ? root as Document : undefined;
     if (typeof els === 'string') {
 
       // Note: very common for people use to id='1,2,3' which is only legal as HTML5 id, but not CSS selectors
       // so if we start with a number, assume it's an id and just return that one item...
       // see https://github.com/gridstack/gridstack.js/issues/2234#issuecomment-1523796562
-      if(!isNaN(+els[0])) { // start with digit
-        const el = root.getElementById(els);
+      if (doc && !isNaN(+els[0])) { // start with digit
+        const el = doc.getElementById(els);
         return el ? [el] : [];
       }
 
@@ -76,24 +77,25 @@ export class Utils {
   }
 
   /** convert a potential selector into actual single element. optional root which defaults to document (for shadow dom) */
-  static getElement(els: GridStackElement, root = document): HTMLElement {
+  static getElement(els: GridStackElement, root: HTMLElement | Document = document): HTMLElement {
+    const doc = ('getElementById' in root) ? root as Document : undefined;
     if (typeof els === 'string') {
       if (!els.length) return null;
-      if (els[0] === '#') {
-        return root.getElementById(els.substring(1));
+      if (doc && els[0] === '#') {
+        return doc.getElementById(els.substring(1));
       }
-      if (els[0] === '.' || els[0] === '[') {
+      if (els[0] === '#' || els[0] === '.' || els[0] === '[') {
         return root.querySelector(els);
       }
 
       // if we start with a digit, assume it's an id (error calling querySelector('#1')) as class are not valid CSS
-      if(!isNaN(+els[0])) { // start with digit
-        return root.getElementById(els);
+      if (doc && !isNaN(+els[0])) { // start with digit
+        return doc.getElementById(els);
       }
 
       // finally try string, then id, then class
       let el = root.querySelector(els);
-      if (!el) { el = root.getElementById(els) }
+      if (doc && !el) { el = doc.getElementById(els) }
       if (!el) { el = root.querySelector('.' + els) }
       return el as HTMLElement;
     }