gridstack 12.3.3 → 12.4.0

package/dist/src/gridstack.scss

@@ -1,5 +1,5 @@
 /**
- * gridstack SASS styles 12.3.3
+ * gridstack SASS styles 12.4.0
  * Copyright (c) 2021-2025 Alain Dumesny - see GridStack root license
  */
 

package/dist/src/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * types.ts 12.3.3
+ * types.ts 12.4.0
  * Copyright (c) 2021-2025 Alain Dumesny - see GridStack root license
  */
 import { GridStack } from './gridstack';
@@ -46,9 +46,9 @@ export interface GridItemHTMLElement extends HTMLElement {
 }
 /**
  * Type representing various ways to specify grid elements.
- * Can be a CSS selector string, HTMLElement, or GridItemHTMLElement.
+ * Can be a CSS selector string, GridItemHTMLElement (HTML element with GS variables when loaded).
  */
-export type GridStackElement = string | HTMLElement | GridItemHTMLElement;
+export type GridStackElement = string | GridItemHTMLElement;
 /**
  * Event handler function types for the .on() method.
  * Different handlers receive different parameters based on the event type.
@@ -249,13 +249,13 @@ export interface GridStackOptions {
      */
     minRow?: number;
     /** If you are using a nonce-based Content Security Policy, pass your nonce here and
-     * GridStack will add it to the <style> elements it creates. */
+     * GridStack will add it to the `<style>` elements it creates. */
     nonce?: string;
     /** class for placeholder (default?: 'grid-stack-placeholder') */
     placeholderClass?: string;
     /** placeholder default content (default?: '') */
     placeholderText?: string;
-    /** allows to override UI resizable options. (default?: { handles: 'se' }) */
+    /** allows to override UI resizable options. default is { handles: 'se', autoHide: true on desktop, false on mobile } */
     resizable?: DDResizeOpt;
     /**
      * if true widgets could be removed by dragging outside of the grid. It could also be a selector string (ex: ".trash"),
@@ -362,13 +362,18 @@ export interface GridStackWidget extends GridStackPosition {
 }
 /** Drag&Drop resize options */
 export interface DDResizeOpt {
-    /** do resize handle hide by default until mouse over ? - default: true on desktop, false on mobile*/
+    /** do resize handle hide by default until mouse over. default: true on desktop, false on mobile */
     autoHide?: boolean;
     /**
      * sides where you can resize from (ex: 'e, se, s, sw, w') - default 'se' (south-east)
      * Note: it is not recommended to resize from the top sides as weird side effect may occur.
     */
     handles?: string;
+    /**
+     * Custom element or query inside the widget node that is used instead of the
+     * generated resize handle.
+     */
+    element?: string | HTMLElement;
 }
 /** Drag&Drop remove options */
 export interface DDRemoveOpt {

package/dist/src/types.js

@@ -1,5 +1,5 @@
 /**
- * types.ts 12.3.3
+ * types.ts 12.4.0
  * Copyright (c) 2021-2025 Alain Dumesny - see GridStack root license
  */
 /**

package/dist/src/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAqB;IAC5C,sBAAsB,EAAE,QAAQ;IAChC,OAAO,EAAE,IAAI;IACb,IAAI,EAAE,IAAI;IACV,UAAU,EAAE,MAAM;IAClB,kBAAkB,EAAE,GAAG;IACvB,cAAc,EAAE,IAAI;IACpB,MAAM,EAAE,EAAE;IACV,SAAS,EAAE,EAAE,MAAM,EAAE,0BAA0B,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;IACjF,MAAM,EAAE,0BAA0B;IAClC,SAAS,EAAE,iBAAiB;IAC5B,MAAM,EAAE,EAAE;IACV,UAAU,EAAE,IAAI;IAChB,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;IACT,gBAAgB,EAAE,wBAAwB;IAC1C,eAAe,EAAE,EAAE;IACnB,gBAAgB,EAAE,EAAE,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,0BAA0B,EAAC;IACnF,SAAS,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE;IAC5B,GAAG,EAAE,MAAM;IAEX,kCAAkC;IAClC,sBAAsB;IACtB,wBAAwB;IACxB,gBAAgB;IAChB,qBAAqB;IACrB,oBAAoB;IACpB,qBAAqB;IACrB,WAAW;CACZ,CAAC","sourcesContent":["/**\r\n * types.ts 12.3.3\r\n * Copyright (c) 2021-2025 Alain Dumesny - see GridStack root license\r\n */\r\n\r\nimport { GridStack } from './gridstack';\r\nimport { GridStackEngine } from './gridstack-engine';\r\n\r\n/**\r\n * Default values for grid options - used during initialization and when saving out grid configuration.\r\n * These values are applied when options are not explicitly provided.\r\n */\r\nexport const gridDefaults: GridStackOptions = {\r\n  alwaysShowResizeHandle: 'mobile',\r\n  animate: true,\r\n  auto: true,\r\n  cellHeight: 'auto',\r\n  cellHeightThrottle: 100,\r\n  cellHeightUnit: 'px',\r\n  column: 12,\r\n  draggable: { handle: '.grid-stack-item-content', appendTo: 'body', scroll: true },\r\n  handle: '.grid-stack-item-content',\r\n  itemClass: 'grid-stack-item',\r\n  margin: 10,\r\n  marginUnit: 'px',\r\n  maxRow: 0,\r\n  minRow: 0,\r\n  placeholderClass: 'grid-stack-placeholder',\r\n  placeholderText: '',\r\n  removableOptions: { accept: 'grid-stack-item', decline: 'grid-stack-non-removable'},\r\n  resizable: { handles: 'se' },\r\n  rtl: 'auto',\r\n\r\n  // **** same as not being set ****\r\n  // disableDrag: false,\r\n  // disableResize: false,\r\n  // float: false,\r\n  // handleClass: null,\r\n  // removable: false,\r\n  // staticGrid: false,\r\n  //removable\r\n};\r\n\r\n/**\r\n * Different layout options when changing the number of columns.\r\n *\r\n * These options control how widgets are repositioned when the grid column count changes.\r\n * Note: The new list may be partially filled if there's a cached layout for that size.\r\n *\r\n * Options:\r\n * - `'list'`: Treat items as a sorted list, keeping them sequentially without resizing (unless too big)\r\n * - `'compact'`: Similar to list, but uses compact() method to fill empty slots by reordering\r\n * - `'moveScale'`: Scale and move items by the ratio of newColumnCount / oldColumnCount\r\n * - `'move'`: Only move items, keep their sizes\r\n * - `'scale'`: Only scale items, keep their positions\r\n * - `'none'`: Leave items unchanged unless they don't fit in the new column count\r\n * - Custom function: Provide your own layout logic\r\n */\r\nexport type ColumnOptions = 'list' | 'compact' | 'moveScale' | 'move' | 'scale' | 'none' |\r\n  ((column: number, oldColumn: number, nodes: GridStackNode[], oldNodes: GridStackNode[]) => void);\r\n/**\r\n * Options for the compact() method to reclaim empty space.\r\n * - `'list'`: Keep items in order, move them up sequentially\r\n * - `'compact'`: Find truly empty spaces, may reorder items for optimal fit\r\n */\r\nexport type CompactOptions = 'list' | 'compact';\r\n/**\r\n * Type representing values that can be either numbers or strings (e.g., dimensions with units).\r\n * Used for properties like width, height, margins that accept both numeric and string values.\r\n */\r\nexport type numberOrString = number | string;\r\n/**\r\n * Extended HTMLElement interface for grid items.\r\n * All grid item DOM elements implement this interface to provide access to their grid data.\r\n */\r\nexport interface GridItemHTMLElement extends HTMLElement {\r\n  /** Pointer to the associated grid node instance containing position, size, and other widget data */\r\n  gridstackNode?: GridStackNode;\r\n  /** @internal Original node data (used for restoring during drag operations) */\r\n  _gridstackNodeOrig?: GridStackNode;\r\n}\r\n\r\n/**\r\n * Type representing various ways to specify grid elements.\r\n * Can be a CSS selector string, HTMLElement, or GridItemHTMLElement.\r\n */\r\nexport type GridStackElement = string | HTMLElement | GridItemHTMLElement;\r\n\r\n/**\r\n * Event handler function types for the .on() method.\r\n * Different handlers receive different parameters based on the event type.\r\n */\r\n\r\n/** General event handler that receives only the event */\r\nexport type GridStackEventHandler = (event: Event) => void;\r\n\r\n/** Element-specific event handler that receives event and affected element */\r\nexport type GridStackElementHandler = (event: Event, el: GridItemHTMLElement) => void;\r\n\r\n/** Node-based event handler that receives event and array of affected nodes */\r\nexport type GridStackNodesHandler = (event: Event, nodes: GridStackNode[]) => void;\r\n\r\n/** Drop event handler that receives previous and new node states */\r\nexport type GridStackDroppedHandler = (event: Event, previousNode: GridStackNode, newNode: GridStackNode) => void;\r\n\r\n/** Union type of all possible event handler types */\r\nexport type GridStackEventHandlerCallback = GridStackEventHandler | GridStackElementHandler | GridStackNodesHandler | GridStackDroppedHandler;\r\n\r\n/**\r\n * Optional callback function called during load() operations.\r\n * Allows custom handling of widget addition/removal for framework integration.\r\n *\r\n * @param parent - The parent HTML element\r\n * @param w - The widget definition\r\n * @param add - True if adding, false if removing\r\n * @param grid - True if this is a grid operation\r\n * @returns The created/modified HTML element, or undefined\r\n */\r\nexport type AddRemoveFcn = (parent: HTMLElement, w: GridStackWidget, add: boolean, grid: boolean) => HTMLElement | undefined;\r\n\r\n/**\r\n * Optional callback function called during save() operations.\r\n * Allows adding custom data to the saved widget structure.\r\n *\r\n * @param node - The internal grid node\r\n * @param w - The widget structure being saved (can be modified)\r\n */\r\nexport type SaveFcn = (node: GridStackNode, w: GridStackWidget) => void;\r\n\r\n/**\r\n * Optional callback function for custom widget content rendering.\r\n * Called during load()/addWidget() to create custom content beyond plain text.\r\n *\r\n * @param el - The widget's content container element\r\n * @param w - The widget definition with content and other properties\r\n */\r\nexport type RenderFcn = (el: HTMLElement, w: GridStackWidget) => void;\r\n\r\n/**\r\n * Optional callback function for custom resize-to-content behavior.\r\n * Called when a widget needs to resize to fit its content.\r\n *\r\n * @param el - The grid item element to resize\r\n */\r\nexport type ResizeToContentFcn = (el: GridItemHTMLElement) => void;\r\n\r\n/**\r\n * Configuration for responsive grid behavior.\r\n *\r\n * Defines how the grid responds to different screen sizes by changing column counts.\r\n * NOTE: Make sure to include the appropriate CSS (gridstack-extra.css) to support responsive behavior.\r\n */\r\nexport interface Responsive {\r\n  /** wanted width to maintain (+-50%) to dynamically pick a column count. NOTE: make sure to have correct extra CSS to support this. */\r\n  columnWidth?: number;\r\n  /** maximum number of columns allowed (default: 12). NOTE: make sure to have correct extra CSS to support this. */\r\n  columnMax?: number;\r\n  /** explicit width:column breakpoints instead of automatic 'columnWidth'. NOTE: make sure to have correct extra CSS to support this. */\r\n  breakpoints?: Breakpoint[];\r\n  /** specify if breakpoints are for window size or grid size (default:false = grid) */\r\n  breakpointForWindow?: boolean;\r\n  /** global re-layout mode when changing columns */\r\n  layout?: ColumnOptions;\r\n}\r\n\r\n/**\r\n * Defines a responsive breakpoint for automatic column count changes.\r\n * Used with the responsive.breakpoints option.\r\n */\r\nexport interface Breakpoint {\r\n  /** Maximum width (in pixels) for this breakpoint to be active */\r\n  w?: number;\r\n  /** Number of columns to use when this breakpoint is active */\r\n  c: number;\r\n  /** Layout mode for this specific breakpoint (overrides global responsive.layout) */\r\n  layout?: ColumnOptions;\r\n  /** TODO: Future feature - specific children layout for this breakpoint */\r\n  // children?: GridStackWidget[];\r\n}\r\n\r\n/**\r\n * Defines the options for a Grid\r\n */\r\nexport interface GridStackOptions {\r\n  /**\r\n   * Accept widgets dragged from other grids or from outside (default: `false`). Can be:\r\n   * - `true`: will accept HTML elements having 'grid-stack-item' as class attribute\r\n   * - `false`: will not accept any external widgets\r\n   * - string: explicit class name to accept instead of default\r\n   * - function: callback called before an item will be accepted when entering a grid\r\n   *\r\n   * @example\r\n   * // Accept all grid items\r\n   * acceptWidgets: true\r\n   *\r\n   * // Accept only items with specific class\r\n   * acceptWidgets: 'my-draggable-item'\r\n   *\r\n   * // Custom validation function\r\n   * acceptWidgets: (el) => {\r\n   *   return el.getAttribute('data-accept') === 'true';\r\n   * }\r\n   *\r\n   * @see {@link http://gridstack.github.io/gridstack.js/demo/two.html} for complete example\r\n   */\r\n  acceptWidgets?: boolean | string | ((element: Element) => boolean);\r\n\r\n  /** possible values (default: `mobile`) - does not apply to non-resizable widgets\r\n    * `false` the resizing handles are only shown while hovering over a widget\r\n    * `true` the resizing handles are always shown\r\n    * 'mobile' if running on a mobile device, default to `true` (since there is no hovering per say), else `false`.\r\n    See [example](http://gridstack.github.io/gridstack.js/demo/mobile.html) */\r\n  alwaysShowResizeHandle?: true | false | 'mobile';\r\n\r\n  /** turns animation on (default?: true) */\r\n  animate?: boolean;\r\n\r\n  /** if false gridstack will not initialize existing items (default?: true) */\r\n  auto?: boolean;\r\n\r\n  /**\r\n   * One cell height (default: 'auto'). Can be:\r\n   * - an integer (px): fixed pixel height\r\n   * - a string (ex: '100px', '10em', '10rem'): CSS length value\r\n   * - 0: library will not generate styles for rows (define your own CSS)\r\n   * - 'auto': height calculated for square cells (width / column) and updated live on window resize\r\n   * - 'initial': similar to 'auto' but stays fixed size during window resizing\r\n   *\r\n   * Note: % values don't work correctly - see demo/cell-height.html\r\n   *\r\n   * @example\r\n   * // Fixed 100px height\r\n   * cellHeight: 100\r\n   *\r\n   * // CSS units\r\n   * cellHeight: '5rem'\r\n   * cellHeight: '100px'\r\n   *\r\n   * // Auto-sizing for square cells\r\n   * cellHeight: 'auto'\r\n   *\r\n   * // No CSS generation (custom styles)\r\n   * cellHeight: 0\r\n   */\r\n  cellHeight?: numberOrString;\r\n\r\n  /** throttle time delay (in ms) used when cellHeight='auto' to improve performance vs usability (default?: 100).\r\n   * A value of 0 will make it instant at a cost of re-creating the CSS file at ever window resize event!\r\n   * */\r\n  cellHeightThrottle?: number;\r\n\r\n  /** (internal) unit for cellHeight (default? 'px') which is set when a string cellHeight with a unit is passed (ex: '10rem') */\r\n  cellHeightUnit?: string;\r\n\r\n  /** list of children item to create when calling load() or addGrid() */\r\n  children?: GridStackWidget[];\r\n\r\n  /** number of columns (default?: 12). Note: IF you change this, CSS also have to change. See https://github.com/gridstack/gridstack.js#change-grid-columns.\r\n   * Note: for nested grids, it is recommended to use 'auto' which will always match the container grid-item current width (in column) to keep inside and outside\r\n   * items always the same. flag is NOT supported for regular non-nested grids.\r\n   */\r\n  column?: number | 'auto';\r\n\r\n  /** responsive column layout for width:column behavior */\r\n  columnOpts?: Responsive;\r\n\r\n  /** additional class on top of '.grid-stack' (which is required for our CSS) to differentiate this instance.\r\n  Note: only used by addGrid(), else your element should have the needed class */\r\n  class?: string;\r\n\r\n  /** disallows dragging of widgets (default?: false) */\r\n  disableDrag?: boolean;\r\n\r\n  /** disallows resizing of widgets (default?: false). */\r\n  disableResize?: boolean;\r\n\r\n  /** allows to override UI draggable options. (default?: { handle?: '.grid-stack-item-content', appendTo?: 'body' }) */\r\n  draggable?: DDDragOpt;\r\n\r\n  /** let user drag nested grid items out of a parent or not (default true - not supported yet) */\r\n  //dragOut?: boolean;\r\n\r\n  /** the type of engine to create (so you can subclass) default to GridStackEngine */\r\n  engineClass?: typeof GridStackEngine;\r\n\r\n  /** enable floating widgets (default?: false) See example (http://gridstack.github.io/gridstack.js/demo/float.html) */\r\n  float?: boolean;\r\n\r\n  /** draggable handle selector (default?: '.grid-stack-item-content') */\r\n  handle?: string;\r\n\r\n  /** draggable handle class (e.g. 'grid-stack-item-content'). If set 'handle' is ignored (default?: null) */\r\n  handleClass?: string;\r\n\r\n  /** additional widget class (default?: 'grid-stack-item') */\r\n  itemClass?: string;\r\n\r\n  /** re-layout mode when we're a subgrid and we are being resized. default to 'list' */\r\n  layout?: ColumnOptions;\r\n\r\n  /** true when widgets are only created when they scroll into view (visible) */\r\n  lazyLoad?: boolean;\r\n\r\n  /**\r\n   * gap between grid item and content (default?: 10). This will set all 4 sides and support the CSS formats below\r\n   *  an integer (px)\r\n   *  a string with possible units (ex: '2em', '20px', '2rem')\r\n   *  string with space separated values (ex: '5px 10px 0 20px' for all 4 sides, or '5em 10em' for top/bottom and left/right pairs like CSS).\r\n   * Note: all sides must have same units (last one wins, default px)\r\n   */\r\n  margin?: numberOrString;\r\n\r\n  /** OLD way to optionally set each side - use margin: '5px 10px 0 20px' instead. Used internally to store each side. */\r\n  marginTop?: numberOrString;\r\n  marginRight?: numberOrString;\r\n  marginBottom?: numberOrString;\r\n  marginLeft?: numberOrString;\r\n\r\n  /** (internal) unit for margin (default? 'px') set when `margin` is set as string with unit (ex: 2rem') */\r\n  marginUnit?: string;\r\n\r\n  /** maximum rows amount. Default? is 0 which means no maximum rows */\r\n  maxRow?: number;\r\n\r\n  /** minimum rows amount which is handy to prevent grid from collapsing when empty. Default is `0`.\r\n   * When no set the `min-height` CSS attribute on the grid div (in pixels) can be used, which will round to the closest row.\r\n   */\r\n  minRow?: number;\r\n\r\n  /** If you are using a nonce-based Content Security Policy, pass your nonce here and\r\n   * GridStack will add it to the <style> elements it creates. */\r\n  nonce?: string;\r\n\r\n  /** class for placeholder (default?: 'grid-stack-placeholder') */\r\n  placeholderClass?: string;\r\n\r\n  /** placeholder default content (default?: '') */\r\n  placeholderText?: string;\r\n\r\n  /** allows to override UI resizable options. (default?: { handles: 'se' }) */\r\n  resizable?: DDResizeOpt;\r\n\r\n  /**\r\n   * if true widgets could be removed by dragging outside of the grid. It could also be a selector string (ex: \".trash\"),\r\n   * in this case widgets will be removed by dropping them there (default?: false)\r\n   * See example (http://gridstack.github.io/gridstack.js/demo/two.html)\r\n   */\r\n  removable?: boolean | string;\r\n\r\n  /** allows to override UI removable options. (default?: { accept: '.grid-stack-item' }) */\r\n  removableOptions?: DDRemoveOpt;\r\n\r\n  /** fix grid number of rows. This is a shortcut of writing `minRow:N, maxRow:N`. (default `0` no constrain) */\r\n  row?: number;\r\n\r\n  /**\r\n   * if true turns grid to RTL. Possible values are true, false, 'auto' (default?: 'auto')\r\n   * See [example](http://gridstack.github.io/gridstack.js/demo/right-to-left(rtl).html)\r\n   */\r\n  rtl?: boolean | 'auto';\r\n\r\n  /** set to true if all grid items (by default, but item can also override) height should be based on content size instead of WidgetItem.h to avoid v-scrollbars.\r\n   * Note: this is still row based, not pixels, so it will use ceil(getBoundingClientRect().height / getCellHeight())\r\n   */\r\n  sizeToContent?: boolean;\r\n\r\n  /**\r\n   * makes grid static (default?: false). If `true` widgets are not movable/resizable.\r\n   * You don't even need draggable/resizable. A CSS class\r\n   * 'grid-stack-static' is also added to the element.\r\n   */\r\n  staticGrid?: boolean;\r\n\r\n  /**\r\n   * @deprecated Not used anymore, styles are now implemented with local CSS variables\r\n   */\r\n  styleInHead?: boolean;\r\n\r\n  /** list of differences in options for automatically created sub-grids under us (inside our grid-items) */\r\n  subGridOpts?: GridStackOptions;\r\n\r\n  /** enable/disable the creation of sub-grids on the fly by dragging items completely\r\n   * over others (nest) vs partially (push). Forces `DDDragOpt.pause=true` to accomplish that. */\r\n  subGridDynamic?: boolean;\r\n}\r\n\r\n/** options used during GridStackEngine.moveNode() */\r\nexport interface GridStackMoveOpts extends GridStackPosition {\r\n  /** node to skip collision */\r\n  skip?: GridStackNode;\r\n  /** do we pack (default true) */\r\n  pack?: boolean;\r\n  /** true if we are calling this recursively to prevent simple swap or coverage collision - default false*/\r\n  nested?: boolean;\r\n  /** vars to calculate other cells coordinates */\r\n  cellWidth?: number;\r\n  cellHeight?: number;\r\n  marginTop?: number;\r\n  marginBottom?: number;\r\n  marginLeft?: number;\r\n  marginRight?: number;\r\n  /** position in pixels of the currently dragged items (for overlap check) */\r\n  rect?: GridStackPosition;\r\n  /** true if we're live resizing */\r\n  resizing?: boolean;\r\n  /** best node (most coverage) we collied with */\r\n  collide?: GridStackNode;\r\n  /** for collision check even if we don't move */\r\n  forceCollide?: boolean;\r\n}\r\n\r\nexport interface GridStackPosition {\r\n  /** widget position x (default?: 0) */\r\n  x?: number;\r\n  /** widget position y (default?: 0) */\r\n  y?: number;\r\n  /** widget dimension width (default?: 1) */\r\n  w?: number;\r\n  /** widget dimension height (default?: 1) */\r\n  h?: number;\r\n}\r\n\r\n/**\r\n * GridStack Widget creation options\r\n */\r\nexport interface GridStackWidget extends GridStackPosition {\r\n  /** if true then x, y parameters will be ignored and widget will be places on the first available position (default?: false) */\r\n  autoPosition?: boolean;\r\n  /** minimum width allowed during resize/creation (default?: undefined = un-constrained) */\r\n  minW?: number;\r\n  /** maximum width allowed during resize/creation (default?: undefined = un-constrained) */\r\n  maxW?: number;\r\n  /** minimum height allowed during resize/creation (default?: undefined = un-constrained) */\r\n  minH?: number;\r\n  /** maximum height allowed during resize/creation (default?: undefined = un-constrained) */\r\n  maxH?: number;\r\n  /** prevent direct resizing by the user (default?: undefined = un-constrained) */\r\n  noResize?: boolean;\r\n  /** prevents direct moving by the user (default?: undefined = un-constrained) */\r\n  noMove?: boolean;\r\n  /** prevents being pushed by other widgets or api (default?: undefined = un-constrained), which is different from `noMove` (user action only) */\r\n  locked?: boolean;\r\n  /** value for `gs-id` stored on the widget (default?: undefined) */\r\n  id?: string;\r\n  /** html to append inside as content */\r\n  content?: string;\r\n  /** true when widgets are only created when they scroll into view (visible) */\r\n  lazyLoad?: boolean;\r\n  /** local (vs grid) override - see GridStackOptions.\r\n   * Note: This also allow you to set a maximum h value (but user changeable during normal resizing) to prevent unlimited content from taking too much space (get scrollbar) */\r\n  sizeToContent?: boolean | number;\r\n  /** local override of GridStack.resizeToContentParent that specify the class to use for the parent (actual) vs child (wanted) height */\r\n  resizeToContentParent?: string;\r\n  /** optional nested grid options and list of children, which then turns into actual instance at runtime to get options from */\r\n  subGridOpts?: GridStackOptions;\r\n}\r\n\r\n/** Drag&Drop resize options */\r\nexport interface DDResizeOpt {\r\n  /** do resize handle hide by default until mouse over ? - default: true on desktop, false on mobile*/\r\n  autoHide?: boolean;\r\n  /**\r\n   * sides where you can resize from (ex: 'e, se, s, sw, w') - default 'se' (south-east)\r\n   * Note: it is not recommended to resize from the top sides as weird side effect may occur.\r\n  */\r\n  handles?: string;\r\n}\r\n\r\n/** Drag&Drop remove options */\r\nexport interface DDRemoveOpt {\r\n  /** class that can be removed (default?: opts.itemClass) */\r\n  accept?: string;\r\n  /** class that cannot be removed (default: 'grid-stack-non-removable') */\r\n  decline?: string;\r\n}\r\n\r\n/** Drag&Drop dragging options */\r\nexport interface DDDragOpt {\r\n  /** class selector of items that can be dragged. default to '.grid-stack-item-content' */\r\n  handle?: string;\r\n  /** default to 'body' */\r\n  appendTo?: string;\r\n  /** if set (true | msec), dragging placement (collision) will only happen after a pause by the user. Note: this is Global */\r\n  pause?: boolean | number;\r\n  /** default to `true` */\r\n  scroll?: boolean;\r\n  /** prevents dragging from starting on specified elements, listed as comma separated selectors (eg: '.no-drag'). default built in is 'input,textarea,button,select,option' */\r\n  cancel?: string;\r\n  /** helper function when dropping: 'clone' or your own method */\r\n  helper?: 'clone' | ((el: HTMLElement) => HTMLElement);\r\n  /** callbacks */\r\n  start?: (event: Event, ui: DDUIData) => void;\r\n  stop?: (event: Event) => void;\r\n  drag?: (event: Event, ui: DDUIData) => void;\r\n}\r\nexport interface Size {\r\n  width: number;\r\n  height: number;\r\n}\r\nexport interface Position {\r\n  top: number;\r\n  left: number;\r\n}\r\nexport interface Rect extends Size, Position {}\r\n\r\n/** data that is passed during drag and resizing callbacks */\r\nexport interface DDUIData {\r\n  position?: Position;\r\n  size?: Size;\r\n  draggable?: HTMLElement;\r\n  /* fields not used by GridStack but sent by jq ? leave in case we go back to them...\r\n  originalPosition? : Position;\r\n  offset?: Position;\r\n  originalSize?: Size;\r\n  element?: HTMLElement[];\r\n  helper?: HTMLElement[];\r\n  originalElement?: HTMLElement[];\r\n  */\r\n}\r\n\r\n/**\r\n * internal runtime descriptions describing the widgets in the grid\r\n */\r\nexport interface GridStackNode extends GridStackWidget {\r\n  /** pointer back to HTML element */\r\n  el?: GridItemHTMLElement;\r\n  /** pointer back to parent Grid instance */\r\n  grid?: GridStack;\r\n  /** actual sub-grid instance */\r\n  subGrid?: GridStack;\r\n  /** allow delay creation when visible */\r\n  visibleObservable?: IntersectionObserver;\r\n  /** @internal internal id used to match when cloning engines or saving column layouts */\r\n  _id?: number;\r\n  /** @internal does the node attr ned to be updated due to changed x,y,w,h values */\r\n  _dirty?: boolean;\r\n  /** @internal */\r\n  _updating?: boolean;\r\n  /** @internal true when over trash/another grid so we don't bother removing drag CSS style that would animate back to old position */\r\n  _isAboutToRemove?: boolean;\r\n  /** @internal true if item came from outside of the grid -> actual item need to be moved over */\r\n  _isExternal?: boolean;\r\n  /** @internal Mouse event that's causing moving|resizing */\r\n  _event?: MouseEvent;\r\n  /** @internal moving vs resizing */\r\n  _moving?: boolean;\r\n  /** @internal is resizing? */\r\n  _resizing?: boolean;\r\n  /** @internal true if we jumped down past item below (one time jump so we don't have to totally pass it) */\r\n  _skipDown?: boolean;\r\n  /** @internal original values before a drag/size */\r\n  _orig?: GridStackPosition;\r\n  /** @internal position in pixels used during collision check  */\r\n  _rect?: GridStackPosition;\r\n  /** @internal top/left pixel location before a drag so we can detect direction of move from last position*/\r\n  _lastUiPosition?: Position;\r\n  /** @internal set on the item being dragged/resized remember the last positions we've tried (but failed) so we don't try again during drag/resize */\r\n  _lastTried?: GridStackPosition;\r\n  /** @internal position willItFit() will use to position the item */\r\n  _willFitPos?: GridStackPosition;\r\n  /** @internal last drag Y pixel position used to incrementally update V scroll bar */\r\n  _prevYPix?: number;\r\n  /** @internal true if we've remove the item from ourself (dragging out) but might revert it back (release on nothing -> goes back) */\r\n  _temporaryRemoved?: boolean;\r\n  /** @internal true if we should remove DOM element on _notify() rather than clearing _id (old way) */\r\n  _removeDOM?: boolean;\r\n  /** @internal original position/size of item if dragged from sidebar */\r\n  _sidebarOrig?: GridStackPosition;\r\n  /** @internal had drag&drop been initialized */\r\n  _initDD?: boolean;\r\n}\r\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAqB;IAC5C,sBAAsB,EAAE,QAAQ;IAChC,OAAO,EAAE,IAAI;IACb,IAAI,EAAE,IAAI;IACV,UAAU,EAAE,MAAM;IAClB,kBAAkB,EAAE,GAAG;IACvB,cAAc,EAAE,IAAI;IACpB,MAAM,EAAE,EAAE;IACV,SAAS,EAAE,EAAE,MAAM,EAAE,0BAA0B,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;IACjF,MAAM,EAAE,0BAA0B;IAClC,SAAS,EAAE,iBAAiB;IAC5B,MAAM,EAAE,EAAE;IACV,UAAU,EAAE,IAAI;IAChB,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;IACT,gBAAgB,EAAE,wBAAwB;IAC1C,eAAe,EAAE,EAAE;IACnB,gBAAgB,EAAE,EAAE,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,0BAA0B,EAAC;IACnF,SAAS,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE;IAC5B,GAAG,EAAE,MAAM;IAEX,kCAAkC;IAClC,sBAAsB;IACtB,wBAAwB;IACxB,gBAAgB;IAChB,qBAAqB;IACrB,oBAAoB;IACpB,qBAAqB;IACrB,WAAW;CACZ,CAAC","sourcesContent":["/**\r\n * types.ts 12.4.0\r\n * Copyright (c) 2021-2025 Alain Dumesny - see GridStack root license\r\n */\r\n\r\nimport { GridStack } from './gridstack';\r\nimport { GridStackEngine } from './gridstack-engine';\r\n\r\n/**\r\n * Default values for grid options - used during initialization and when saving out grid configuration.\r\n * These values are applied when options are not explicitly provided.\r\n */\r\nexport const gridDefaults: GridStackOptions = {\r\n  alwaysShowResizeHandle: 'mobile',\r\n  animate: true,\r\n  auto: true,\r\n  cellHeight: 'auto',\r\n  cellHeightThrottle: 100,\r\n  cellHeightUnit: 'px',\r\n  column: 12,\r\n  draggable: { handle: '.grid-stack-item-content', appendTo: 'body', scroll: true },\r\n  handle: '.grid-stack-item-content',\r\n  itemClass: 'grid-stack-item',\r\n  margin: 10,\r\n  marginUnit: 'px',\r\n  maxRow: 0,\r\n  minRow: 0,\r\n  placeholderClass: 'grid-stack-placeholder',\r\n  placeholderText: '',\r\n  removableOptions: { accept: 'grid-stack-item', decline: 'grid-stack-non-removable'},\r\n  resizable: { handles: 'se' },\r\n  rtl: 'auto',\r\n\r\n  // **** same as not being set ****\r\n  // disableDrag: false,\r\n  // disableResize: false,\r\n  // float: false,\r\n  // handleClass: null,\r\n  // removable: false,\r\n  // staticGrid: false,\r\n  //removable\r\n};\r\n\r\n/**\r\n * Different layout options when changing the number of columns.\r\n *\r\n * These options control how widgets are repositioned when the grid column count changes.\r\n * Note: The new list may be partially filled if there's a cached layout for that size.\r\n *\r\n * Options:\r\n * - `'list'`: Treat items as a sorted list, keeping them sequentially without resizing (unless too big)\r\n * - `'compact'`: Similar to list, but uses compact() method to fill empty slots by reordering\r\n * - `'moveScale'`: Scale and move items by the ratio of newColumnCount / oldColumnCount\r\n * - `'move'`: Only move items, keep their sizes\r\n * - `'scale'`: Only scale items, keep their positions\r\n * - `'none'`: Leave items unchanged unless they don't fit in the new column count\r\n * - Custom function: Provide your own layout logic\r\n */\r\nexport type ColumnOptions = 'list' | 'compact' | 'moveScale' | 'move' | 'scale' | 'none' |\r\n  ((column: number, oldColumn: number, nodes: GridStackNode[], oldNodes: GridStackNode[]) => void);\r\n/**\r\n * Options for the compact() method to reclaim empty space.\r\n * - `'list'`: Keep items in order, move them up sequentially\r\n * - `'compact'`: Find truly empty spaces, may reorder items for optimal fit\r\n */\r\nexport type CompactOptions = 'list' | 'compact';\r\n/**\r\n * Type representing values that can be either numbers or strings (e.g., dimensions with units).\r\n * Used for properties like width, height, margins that accept both numeric and string values.\r\n */\r\nexport type numberOrString = number | string;\r\n/**\r\n * Extended HTMLElement interface for grid items.\r\n * All grid item DOM elements implement this interface to provide access to their grid data.\r\n */\r\nexport interface GridItemHTMLElement extends HTMLElement {\r\n  /** Pointer to the associated grid node instance containing position, size, and other widget data */\r\n  gridstackNode?: GridStackNode;\r\n  /** @internal Original node data (used for restoring during drag operations) */\r\n  _gridstackNodeOrig?: GridStackNode;\r\n}\r\n\r\n/**\r\n * Type representing various ways to specify grid elements.\r\n * Can be a CSS selector string, GridItemHTMLElement (HTML element with GS variables when loaded).\r\n */\r\nexport type GridStackElement = string | GridItemHTMLElement;\r\n\r\n/**\r\n * Event handler function types for the .on() method.\r\n * Different handlers receive different parameters based on the event type.\r\n */\r\n\r\n/** General event handler that receives only the event */\r\nexport type GridStackEventHandler = (event: Event) => void;\r\n\r\n/** Element-specific event handler that receives event and affected element */\r\nexport type GridStackElementHandler = (event: Event, el: GridItemHTMLElement) => void;\r\n\r\n/** Node-based event handler that receives event and array of affected nodes */\r\nexport type GridStackNodesHandler = (event: Event, nodes: GridStackNode[]) => void;\r\n\r\n/** Drop event handler that receives previous and new node states */\r\nexport type GridStackDroppedHandler = (event: Event, previousNode: GridStackNode, newNode: GridStackNode) => void;\r\n\r\n/** Union type of all possible event handler types */\r\nexport type GridStackEventHandlerCallback = GridStackEventHandler | GridStackElementHandler | GridStackNodesHandler | GridStackDroppedHandler;\r\n\r\n/**\r\n * Optional callback function called during load() operations.\r\n * Allows custom handling of widget addition/removal for framework integration.\r\n *\r\n * @param parent - The parent HTML element\r\n * @param w - The widget definition\r\n * @param add - True if adding, false if removing\r\n * @param grid - True if this is a grid operation\r\n * @returns The created/modified HTML element, or undefined\r\n */\r\nexport type AddRemoveFcn = (parent: HTMLElement, w: GridStackWidget, add: boolean, grid: boolean) => HTMLElement | undefined;\r\n\r\n/**\r\n * Optional callback function called during save() operations.\r\n * Allows adding custom data to the saved widget structure.\r\n *\r\n * @param node - The internal grid node\r\n * @param w - The widget structure being saved (can be modified)\r\n */\r\nexport type SaveFcn = (node: GridStackNode, w: GridStackWidget) => void;\r\n\r\n/**\r\n * Optional callback function for custom widget content rendering.\r\n * Called during load()/addWidget() to create custom content beyond plain text.\r\n *\r\n * @param el - The widget's content container element\r\n * @param w - The widget definition with content and other properties\r\n */\r\nexport type RenderFcn = (el: HTMLElement, w: GridStackWidget) => void;\r\n\r\n/**\r\n * Optional callback function for custom resize-to-content behavior.\r\n * Called when a widget needs to resize to fit its content.\r\n *\r\n * @param el - The grid item element to resize\r\n */\r\nexport type ResizeToContentFcn = (el: GridItemHTMLElement) => void;\r\n\r\n/**\r\n * Configuration for responsive grid behavior.\r\n *\r\n * Defines how the grid responds to different screen sizes by changing column counts.\r\n * NOTE: Make sure to include the appropriate CSS (gridstack-extra.css) to support responsive behavior.\r\n */\r\nexport interface Responsive {\r\n  /** wanted width to maintain (+-50%) to dynamically pick a column count. NOTE: make sure to have correct extra CSS to support this. */\r\n  columnWidth?: number;\r\n  /** maximum number of columns allowed (default: 12). NOTE: make sure to have correct extra CSS to support this. */\r\n  columnMax?: number;\r\n  /** explicit width:column breakpoints instead of automatic 'columnWidth'. NOTE: make sure to have correct extra CSS to support this. */\r\n  breakpoints?: Breakpoint[];\r\n  /** specify if breakpoints are for window size or grid size (default:false = grid) */\r\n  breakpointForWindow?: boolean;\r\n  /** global re-layout mode when changing columns */\r\n  layout?: ColumnOptions;\r\n}\r\n\r\n/**\r\n * Defines a responsive breakpoint for automatic column count changes.\r\n * Used with the responsive.breakpoints option.\r\n */\r\nexport interface Breakpoint {\r\n  /** Maximum width (in pixels) for this breakpoint to be active */\r\n  w?: number;\r\n  /** Number of columns to use when this breakpoint is active */\r\n  c: number;\r\n  /** Layout mode for this specific breakpoint (overrides global responsive.layout) */\r\n  layout?: ColumnOptions;\r\n  /** TODO: Future feature - specific children layout for this breakpoint */\r\n  // children?: GridStackWidget[];\r\n}\r\n\r\n/**\r\n * Defines the options for a Grid\r\n */\r\nexport interface GridStackOptions {\r\n  /**\r\n   * Accept widgets dragged from other grids or from outside (default: `false`). Can be:\r\n   * - `true`: will accept HTML elements having 'grid-stack-item' as class attribute\r\n   * - `false`: will not accept any external widgets\r\n   * - string: explicit class name to accept instead of default\r\n   * - function: callback called before an item will be accepted when entering a grid\r\n   *\r\n   * @example\r\n   * // Accept all grid items\r\n   * acceptWidgets: true\r\n   *\r\n   * // Accept only items with specific class\r\n   * acceptWidgets: 'my-draggable-item'\r\n   *\r\n   * // Custom validation function\r\n   * acceptWidgets: (el) => {\r\n   *   return el.getAttribute('data-accept') === 'true';\r\n   * }\r\n   *\r\n   * @see {@link http://gridstack.github.io/gridstack.js/demo/two.html} for complete example\r\n   */\r\n  acceptWidgets?: boolean | string | ((element: Element) => boolean);\r\n\r\n  /** possible values (default: `mobile`) - does not apply to non-resizable widgets\r\n    * `false` the resizing handles are only shown while hovering over a widget\r\n    * `true` the resizing handles are always shown\r\n    * 'mobile' if running on a mobile device, default to `true` (since there is no hovering per say), else `false`.\r\n    See [example](http://gridstack.github.io/gridstack.js/demo/mobile.html) */\r\n  alwaysShowResizeHandle?: true | false | 'mobile';\r\n\r\n  /** turns animation on (default?: true) */\r\n  animate?: boolean;\r\n\r\n  /** if false gridstack will not initialize existing items (default?: true) */\r\n  auto?: boolean;\r\n\r\n  /**\r\n   * One cell height (default: 'auto'). Can be:\r\n   * - an integer (px): fixed pixel height\r\n   * - a string (ex: '100px', '10em', '10rem'): CSS length value\r\n   * - 0: library will not generate styles for rows (define your own CSS)\r\n   * - 'auto': height calculated for square cells (width / column) and updated live on window resize\r\n   * - 'initial': similar to 'auto' but stays fixed size during window resizing\r\n   *\r\n   * Note: % values don't work correctly - see demo/cell-height.html\r\n   *\r\n   * @example\r\n   * // Fixed 100px height\r\n   * cellHeight: 100\r\n   *\r\n   * // CSS units\r\n   * cellHeight: '5rem'\r\n   * cellHeight: '100px'\r\n   *\r\n   * // Auto-sizing for square cells\r\n   * cellHeight: 'auto'\r\n   *\r\n   * // No CSS generation (custom styles)\r\n   * cellHeight: 0\r\n   */\r\n  cellHeight?: numberOrString;\r\n\r\n  /** throttle time delay (in ms) used when cellHeight='auto' to improve performance vs usability (default?: 100).\r\n   * A value of 0 will make it instant at a cost of re-creating the CSS file at ever window resize event!\r\n   * */\r\n  cellHeightThrottle?: number;\r\n\r\n  /** (internal) unit for cellHeight (default? 'px') which is set when a string cellHeight with a unit is passed (ex: '10rem') */\r\n  cellHeightUnit?: string;\r\n\r\n  /** list of children item to create when calling load() or addGrid() */\r\n  children?: GridStackWidget[];\r\n\r\n  /** number of columns (default?: 12). Note: IF you change this, CSS also have to change. See https://github.com/gridstack/gridstack.js#change-grid-columns.\r\n   * Note: for nested grids, it is recommended to use 'auto' which will always match the container grid-item current width (in column) to keep inside and outside\r\n   * items always the same. flag is NOT supported for regular non-nested grids.\r\n   */\r\n  column?: number | 'auto';\r\n\r\n  /** responsive column layout for width:column behavior */\r\n  columnOpts?: Responsive;\r\n\r\n  /** additional class on top of '.grid-stack' (which is required for our CSS) to differentiate this instance.\r\n  Note: only used by addGrid(), else your element should have the needed class */\r\n  class?: string;\r\n\r\n  /** disallows dragging of widgets (default?: false) */\r\n  disableDrag?: boolean;\r\n\r\n  /** disallows resizing of widgets (default?: false). */\r\n  disableResize?: boolean;\r\n\r\n  /** allows to override UI draggable options. (default?: { handle?: '.grid-stack-item-content', appendTo?: 'body' }) */\r\n  draggable?: DDDragOpt;\r\n\r\n  /** let user drag nested grid items out of a parent or not (default true - not supported yet) */\r\n  //dragOut?: boolean;\r\n\r\n  /** the type of engine to create (so you can subclass) default to GridStackEngine */\r\n  engineClass?: typeof GridStackEngine;\r\n\r\n  /** enable floating widgets (default?: false) See example (http://gridstack.github.io/gridstack.js/demo/float.html) */\r\n  float?: boolean;\r\n\r\n  /** draggable handle selector (default?: '.grid-stack-item-content') */\r\n  handle?: string;\r\n\r\n  /** draggable handle class (e.g. 'grid-stack-item-content'). If set 'handle' is ignored (default?: null) */\r\n  handleClass?: string;\r\n\r\n  /** additional widget class (default?: 'grid-stack-item') */\r\n  itemClass?: string;\r\n\r\n  /** re-layout mode when we're a subgrid and we are being resized. default to 'list' */\r\n  layout?: ColumnOptions;\r\n\r\n  /** true when widgets are only created when they scroll into view (visible) */\r\n  lazyLoad?: boolean;\r\n\r\n  /**\r\n   * gap between grid item and content (default?: 10). This will set all 4 sides and support the CSS formats below\r\n   *  an integer (px)\r\n   *  a string with possible units (ex: '2em', '20px', '2rem')\r\n   *  string with space separated values (ex: '5px 10px 0 20px' for all 4 sides, or '5em 10em' for top/bottom and left/right pairs like CSS).\r\n   * Note: all sides must have same units (last one wins, default px)\r\n   */\r\n  margin?: numberOrString;\r\n\r\n  /** OLD way to optionally set each side - use margin: '5px 10px 0 20px' instead. Used internally to store each side. */\r\n  marginTop?: numberOrString;\r\n  marginRight?: numberOrString;\r\n  marginBottom?: numberOrString;\r\n  marginLeft?: numberOrString;\r\n\r\n  /** (internal) unit for margin (default? 'px') set when `margin` is set as string with unit (ex: 2rem') */\r\n  marginUnit?: string;\r\n\r\n  /** maximum rows amount. Default? is 0 which means no maximum rows */\r\n  maxRow?: number;\r\n\r\n  /** minimum rows amount which is handy to prevent grid from collapsing when empty. Default is `0`.\r\n   * When no set the `min-height` CSS attribute on the grid div (in pixels) can be used, which will round to the closest row.\r\n   */\r\n  minRow?: number;\r\n\r\n  /** If you are using a nonce-based Content Security Policy, pass your nonce here and\r\n   * GridStack will add it to the `<style>` elements it creates. */\r\n  nonce?: string;\r\n\r\n  /** class for placeholder (default?: 'grid-stack-placeholder') */\r\n  placeholderClass?: string;\r\n\r\n  /** placeholder default content (default?: '') */\r\n  placeholderText?: string;\r\n\r\n  /** allows to override UI resizable options. default is { handles: 'se', autoHide: true on desktop, false on mobile } */\r\n  resizable?: DDResizeOpt;\r\n\r\n  /**\r\n   * if true widgets could be removed by dragging outside of the grid. It could also be a selector string (ex: \".trash\"),\r\n   * in this case widgets will be removed by dropping them there (default?: false)\r\n   * See example (http://gridstack.github.io/gridstack.js/demo/two.html)\r\n   */\r\n  removable?: boolean | string;\r\n\r\n  /** allows to override UI removable options. (default?: { accept: '.grid-stack-item' }) */\r\n  removableOptions?: DDRemoveOpt;\r\n\r\n  /** fix grid number of rows. This is a shortcut of writing `minRow:N, maxRow:N`. (default `0` no constrain) */\r\n  row?: number;\r\n\r\n  /**\r\n   * if true turns grid to RTL. Possible values are true, false, 'auto' (default?: 'auto')\r\n   * See [example](http://gridstack.github.io/gridstack.js/demo/right-to-left(rtl).html)\r\n   */\r\n  rtl?: boolean | 'auto';\r\n\r\n  /** set to true if all grid items (by default, but item can also override) height should be based on content size instead of WidgetItem.h to avoid v-scrollbars.\r\n   * Note: this is still row based, not pixels, so it will use ceil(getBoundingClientRect().height / getCellHeight())\r\n   */\r\n  sizeToContent?: boolean;\r\n\r\n  /**\r\n   * makes grid static (default?: false). If `true` widgets are not movable/resizable.\r\n   * You don't even need draggable/resizable. A CSS class\r\n   * 'grid-stack-static' is also added to the element.\r\n   */\r\n  staticGrid?: boolean;\r\n\r\n  /**\r\n   * @deprecated Not used anymore, styles are now implemented with local CSS variables\r\n   */\r\n  styleInHead?: boolean;\r\n\r\n  /** list of differences in options for automatically created sub-grids under us (inside our grid-items) */\r\n  subGridOpts?: GridStackOptions;\r\n\r\n  /** enable/disable the creation of sub-grids on the fly by dragging items completely\r\n   * over others (nest) vs partially (push). Forces `DDDragOpt.pause=true` to accomplish that. */\r\n  subGridDynamic?: boolean;\r\n}\r\n\r\n/** options used during GridStackEngine.moveNode() */\r\nexport interface GridStackMoveOpts extends GridStackPosition {\r\n  /** node to skip collision */\r\n  skip?: GridStackNode;\r\n  /** do we pack (default true) */\r\n  pack?: boolean;\r\n  /** true if we are calling this recursively to prevent simple swap or coverage collision - default false*/\r\n  nested?: boolean;\r\n  /** vars to calculate other cells coordinates */\r\n  cellWidth?: number;\r\n  cellHeight?: number;\r\n  marginTop?: number;\r\n  marginBottom?: number;\r\n  marginLeft?: number;\r\n  marginRight?: number;\r\n  /** position in pixels of the currently dragged items (for overlap check) */\r\n  rect?: GridStackPosition;\r\n  /** true if we're live resizing */\r\n  resizing?: boolean;\r\n  /** best node (most coverage) we collied with */\r\n  collide?: GridStackNode;\r\n  /** for collision check even if we don't move */\r\n  forceCollide?: boolean;\r\n}\r\n\r\nexport interface GridStackPosition {\r\n  /** widget position x (default?: 0) */\r\n  x?: number;\r\n  /** widget position y (default?: 0) */\r\n  y?: number;\r\n  /** widget dimension width (default?: 1) */\r\n  w?: number;\r\n  /** widget dimension height (default?: 1) */\r\n  h?: number;\r\n}\r\n\r\n/**\r\n * GridStack Widget creation options\r\n */\r\nexport interface GridStackWidget extends GridStackPosition {\r\n  /** if true then x, y parameters will be ignored and widget will be places on the first available position (default?: false) */\r\n  autoPosition?: boolean;\r\n  /** minimum width allowed during resize/creation (default?: undefined = un-constrained) */\r\n  minW?: number;\r\n  /** maximum width allowed during resize/creation (default?: undefined = un-constrained) */\r\n  maxW?: number;\r\n  /** minimum height allowed during resize/creation (default?: undefined = un-constrained) */\r\n  minH?: number;\r\n  /** maximum height allowed during resize/creation (default?: undefined = un-constrained) */\r\n  maxH?: number;\r\n  /** prevent direct resizing by the user (default?: undefined = un-constrained) */\r\n  noResize?: boolean;\r\n  /** prevents direct moving by the user (default?: undefined = un-constrained) */\r\n  noMove?: boolean;\r\n  /** prevents being pushed by other widgets or api (default?: undefined = un-constrained), which is different from `noMove` (user action only) */\r\n  locked?: boolean;\r\n  /** value for `gs-id` stored on the widget (default?: undefined) */\r\n  id?: string;\r\n  /** html to append inside as content */\r\n  content?: string;\r\n  /** true when widgets are only created when they scroll into view (visible) */\r\n  lazyLoad?: boolean;\r\n  /** local (vs grid) override - see GridStackOptions.\r\n   * Note: This also allow you to set a maximum h value (but user changeable during normal resizing) to prevent unlimited content from taking too much space (get scrollbar) */\r\n  sizeToContent?: boolean | number;\r\n  /** local override of GridStack.resizeToContentParent that specify the class to use for the parent (actual) vs child (wanted) height */\r\n  resizeToContentParent?: string;\r\n  /** optional nested grid options and list of children, which then turns into actual instance at runtime to get options from */\r\n  subGridOpts?: GridStackOptions;\r\n}\r\n\r\n/** Drag&Drop resize options */\r\nexport interface DDResizeOpt {\r\n  /** do resize handle hide by default until mouse over. default: true on desktop, false on mobile */\r\n  autoHide?: boolean;\r\n  /**\r\n   * sides where you can resize from (ex: 'e, se, s, sw, w') - default 'se' (south-east)\r\n   * Note: it is not recommended to resize from the top sides as weird side effect may occur.\r\n  */\r\n  handles?: string;\r\n  /**\r\n   * Custom element or query inside the widget node that is used instead of the\r\n   * generated resize handle.\r\n   */\r\n  element?: string | HTMLElement\r\n}\r\n\r\n/** Drag&Drop remove options */\r\nexport interface DDRemoveOpt {\r\n  /** class that can be removed (default?: opts.itemClass) */\r\n  accept?: string;\r\n  /** class that cannot be removed (default: 'grid-stack-non-removable') */\r\n  decline?: string;\r\n}\r\n\r\n/** Drag&Drop dragging options */\r\nexport interface DDDragOpt {\r\n  /** class selector of items that can be dragged. default to '.grid-stack-item-content' */\r\n  handle?: string;\r\n  /** default to 'body' */\r\n  appendTo?: string;\r\n  /** if set (true | msec), dragging placement (collision) will only happen after a pause by the user. Note: this is Global */\r\n  pause?: boolean | number;\r\n  /** default to `true` */\r\n  scroll?: boolean;\r\n  /** prevents dragging from starting on specified elements, listed as comma separated selectors (eg: '.no-drag'). default built in is 'input,textarea,button,select,option' */\r\n  cancel?: string;\r\n  /** helper function when dropping: 'clone' or your own method */\r\n  helper?: 'clone' | ((el: HTMLElement) => HTMLElement);\r\n  /** callbacks */\r\n  start?: (event: Event, ui: DDUIData) => void;\r\n  stop?: (event: Event) => void;\r\n  drag?: (event: Event, ui: DDUIData) => void;\r\n}\r\nexport interface Size {\r\n  width: number;\r\n  height: number;\r\n}\r\nexport interface Position {\r\n  top: number;\r\n  left: number;\r\n}\r\nexport interface Rect extends Size, Position {}\r\n\r\n/** data that is passed during drag and resizing callbacks */\r\nexport interface DDUIData {\r\n  position?: Position;\r\n  size?: Size;\r\n  draggable?: HTMLElement;\r\n  /* fields not used by GridStack but sent by jq ? leave in case we go back to them...\r\n  originalPosition? : Position;\r\n  offset?: Position;\r\n  originalSize?: Size;\r\n  element?: HTMLElement[];\r\n  helper?: HTMLElement[];\r\n  originalElement?: HTMLElement[];\r\n  */\r\n}\r\n\r\n/**\r\n * internal runtime descriptions describing the widgets in the grid\r\n */\r\nexport interface GridStackNode extends GridStackWidget {\r\n  /** pointer back to HTML element */\r\n  el?: GridItemHTMLElement;\r\n  /** pointer back to parent Grid instance */\r\n  grid?: GridStack;\r\n  /** actual sub-grid instance */\r\n  subGrid?: GridStack;\r\n  /** allow delay creation when visible */\r\n  visibleObservable?: IntersectionObserver;\r\n  /** @internal internal id used to match when cloning engines or saving column layouts */\r\n  _id?: number;\r\n  /** @internal does the node attr ned to be updated due to changed x,y,w,h values */\r\n  _dirty?: boolean;\r\n  /** @internal */\r\n  _updating?: boolean;\r\n  /** @internal true when over trash/another grid so we don't bother removing drag CSS style that would animate back to old position */\r\n  _isAboutToRemove?: boolean;\r\n  /** @internal true if item came from outside of the grid -> actual item need to be moved over */\r\n  _isExternal?: boolean;\r\n  /** @internal Mouse event that's causing moving|resizing */\r\n  _event?: MouseEvent;\r\n  /** @internal moving vs resizing */\r\n  _moving?: boolean;\r\n  /** @internal is resizing? */\r\n  _resizing?: boolean;\r\n  /** @internal true if we jumped down past item below (one time jump so we don't have to totally pass it) */\r\n  _skipDown?: boolean;\r\n  /** @internal original values before a drag/size */\r\n  _orig?: GridStackPosition;\r\n  /** @internal position in pixels used during collision check  */\r\n  _rect?: GridStackPosition;\r\n  /** @internal top/left pixel location before a drag so we can detect direction of move from last position*/\r\n  _lastUiPosition?: Position;\r\n  /** @internal set on the item being dragged/resized remember the last positions we've tried (but failed) so we don't try again during drag/resize */\r\n  _lastTried?: GridStackPosition;\r\n  /** @internal position willItFit() will use to position the item */\r\n  _willFitPos?: GridStackPosition;\r\n  /** @internal last drag Y pixel position used to incrementally update V scroll bar */\r\n  _prevYPix?: number;\r\n  /** @internal true if we've remove the item from ourself (dragging out) but might revert it back (release on nothing -> goes back) */\r\n  _temporaryRemoved?: boolean;\r\n  /** @internal true if we should remove DOM element on _notify() rather than clearing _id (old way) */\r\n  _removeDOM?: boolean;\r\n  /** @internal original position/size of item if dragged from sidebar */\r\n  _sidebarOrig?: GridStackPosition;\r\n  /** @internal had drag&drop been initialized */\r\n  _initDD?: boolean;\r\n}\r\n"]}

package/dist/src/utils.d.ts

@@ -1,8 +1,7 @@
 /**
- * utils.ts 12.3.3
+ * utils.ts 12.4.0
  * Copyright (c) 2021-2025 Alain Dumesny - see GridStack root license
  */
-import { GridStackElement, GridStackNode, numberOrString, GridStackPosition, GridStackWidget } from './types';
 export interface HeightData {
     h: number;
     unit: string;
@@ -13,271 +12,3 @@ export interface DragTransform {
     xOffset: number;
     yOffset: number;
 }
-/**
- * Collection of utility methods used throughout GridStack.
- * These are general-purpose helper functions for DOM manipulation,
- * positioning calculations, object operations, and more.
- */
-export declare class Utils {
-    /**
-     * Convert a potential selector into an actual list of HTML elements.
-     * Supports CSS selectors, element references, and special ID handling.
-     *
-     * @param els selector string, HTMLElement, or array of elements
-     * @param root optional root element to search within (defaults to document, useful for shadow DOM)
-     * @returns array of HTML elements matching the selector
-     *
-     * @example
-     * const elements = Utils.getElements('.grid-item');
-     * const byId = Utils.getElements('#myWidget');
-     * const fromShadow = Utils.getElements('.item', shadowRoot);
-     */
-    static getElements(els: GridStackElement, root?: HTMLElement | Document): HTMLElement[];
-    /**
-     * Convert a potential selector into a single HTML element.
-     * Similar to getElements() but returns only the first match.
-     *
-     * @param els selector string or HTMLElement
-     * @param root optional root element to search within (defaults to document)
-     * @returns the first HTML element matching the selector, or null if not found
-     *
-     * @example
-     * const element = Utils.getElement('#myWidget');
-     * const first = Utils.getElement('.grid-item');
-     */
-    static getElement(els: GridStackElement, root?: HTMLElement | Document): HTMLElement;
-    /**
-     * Check if a widget should be lazy loaded based on node or grid settings.
-     *
-     * @param n the grid node to check
-     * @returns true if the item should be lazy loaded
-     *
-     * @example
-     * if (Utils.lazyLoad(node)) {
-     *   // Set up intersection observer for lazy loading
-     * }
-     */
-    static lazyLoad(n: GridStackNode): boolean;
-    /**
-     * Create a div element with the specified CSS classes.
-     *
-     * @param classes array of CSS class names to add
-     * @param parent optional parent element to append the div to
-     * @returns the created div element
-     *
-     * @example
-     * const div = Utils.createDiv(['grid-item', 'draggable']);
-     * const nested = Utils.createDiv(['content'], parentDiv);
-     */
-    static createDiv(classes: string[], parent?: HTMLElement): HTMLElement;
-    /**
-     * Check if a widget should resize to fit its content.
-     *
-     * @param n the grid node to check (can be undefined)
-     * @param strict if true, only returns true for explicit sizeToContent:true (not numbers)
-     * @returns true if the widget should resize to content
-     *
-     * @example
-     * if (Utils.shouldSizeToContent(node)) {
-     *   // Trigger content-based resizing
-     * }
-     */
-    static shouldSizeToContent(n: GridStackNode | undefined, strict?: boolean): boolean;
-    /**
-     * Check if two grid positions overlap/intersect.
-     *
-     * @param a first position with x, y, w, h properties
-     * @param b second position with x, y, w, h properties
-     * @returns true if the positions overlap
-     *
-     * @example
-     * const overlaps = Utils.isIntercepted(
-     *   {x: 0, y: 0, w: 2, h: 1},
-     *   {x: 1, y: 0, w: 2, h: 1}
-     * ); // true - they overlap
-     */
-    static isIntercepted(a: GridStackPosition, b: GridStackPosition): boolean;
-    /**
-     * Check if two grid positions are touching (edges or corners).
-     *
-     * @param a first position
-     * @param b second position
-     * @returns true if the positions are touching
-     *
-     * @example
-     * const touching = Utils.isTouching(
-     *   {x: 0, y: 0, w: 2, h: 1},
-     *   {x: 2, y: 0, w: 1, h: 1}
-     * ); // true - they share an edge
-     */
-    static isTouching(a: GridStackPosition, b: GridStackPosition): boolean;
-    /**
-     * Calculate the overlapping area between two grid positions.
-     *
-     * @param a first position
-     * @param b second position
-     * @returns the area of overlap (0 if no overlap)
-     *
-     * @example
-     * const overlap = Utils.areaIntercept(
-     *   {x: 0, y: 0, w: 3, h: 2},
-     *   {x: 1, y: 0, w: 3, h: 2}
-     * ); // returns 4 (2x2 overlap)
-     */
-    static areaIntercept(a: GridStackPosition, b: GridStackPosition): number;
-    /**
-     * Calculate the total area of a grid position.
-     *
-     * @param a position with width and height
-     * @returns the total area (width * height)
-     *
-     * @example
-     * const area = Utils.area({x: 0, y: 0, w: 3, h: 2}); // returns 6
-     */
-    static area(a: GridStackPosition): number;
-    /**
-     * Sort an array of grid nodes by position (y first, then x).
-     *
-     * @param nodes array of nodes to sort
-     * @param dir sort direction: 1 for ascending (top-left first), -1 for descending
-     * @returns the sorted array (modifies original)
-     *
-     * @example
-     * const sorted = Utils.sort(nodes); // Sort top-left to bottom-right
-     * const reverse = Utils.sort(nodes, -1); // Sort bottom-right to top-left
-     */
-    static sort(nodes: GridStackNode[], dir?: 1 | -1): GridStackNode[];
-    /**
-     * Find a grid node by its ID.
-     *
-     * @param nodes array of nodes to search
-     * @param id the ID to search for
-     * @returns the node with matching ID, or undefined if not found
-     *
-     * @example
-     * const node = Utils.find(nodes, 'widget-1');
-     * if (node) console.log('Found node at:', node.x, node.y);
-     */
-    static find(nodes: GridStackNode[], id: string): GridStackNode | undefined;
-    /**
-     * Convert various value types to boolean.
-     * Handles strings like 'false', 'no', '0' as false.
-     *
-     * @param v value to convert
-     * @returns boolean representation
-     *
-     * @example
-     * Utils.toBool('true');  // true
-     * Utils.toBool('false'); // false
-     * Utils.toBool('no');    // false
-     * Utils.toBool('1');     // true
-     */
-    static toBool(v: unknown): boolean;
-    /**
-     * Convert a string value to a number, handling null and empty strings.
-     *
-     * @param value string or null value to convert
-     * @returns number value, or undefined for null/empty strings
-     *
-     * @example
-     * Utils.toNumber('42');  // 42
-     * Utils.toNumber('');    // undefined
-     * Utils.toNumber(null);  // undefined
-     */
-    static toNumber(value: null | string): number;
-    /**
-     * Parse a height value with units into numeric value and unit string.
-     * Supports px, em, rem, vh, vw, %, cm, mm units.
-     *
-     * @param val height value as number or string with units
-     * @returns object with h (height) and unit properties
-     *
-     * @example
-     * Utils.parseHeight('100px');  // {h: 100, unit: 'px'}
-     * Utils.parseHeight('2rem');   // {h: 2, unit: 'rem'}
-     * Utils.parseHeight(50);       // {h: 50, unit: 'px'}
-     */
-    static parseHeight(val: numberOrString): HeightData;
-    /**
-     * Copy unset fields from source objects to target object (shallow merge with defaults).
-     * Similar to Object.assign but only sets undefined/null fields.
-     *
-     * @param target the object to copy defaults into
-     * @param sources one or more source objects to copy defaults from
-     * @returns the modified target object
-     *
-     * @example
-     * const config = { width: 100 };
-     * Utils.defaults(config, { width: 200, height: 50 });
-     * // config is now { width: 100, height: 50 }
-     */
-    static defaults(target: any, ...sources: any[]): {};
-    /**
-     * Compare two objects for equality (shallow comparison).
-     * Checks if objects have the same fields and values at one level deep.
-     *
-     * @param a first object to compare
-     * @param b second object to compare
-     * @returns true if objects have the same values
-     *
-     * @example
-     * Utils.same({x: 1, y: 2}, {x: 1, y: 2}); // true
-     * Utils.same({x: 1}, {x: 1, y: 2}); // false
-     */
-    static same(a: unknown, b: unknown): boolean;
-    /**
-     * Copy position and size properties from one widget to another.
-     * Copies x, y, w, h and optionally min/max constraints.
-     *
-     * @param a target widget to copy to
-     * @param b source widget to copy from
-     * @param doMinMax if true, also copy min/max width/height constraints
-     * @returns the target widget (a)
-     *
-     * @example
-     * Utils.copyPos(widget1, widget2); // Copy position/size
-     * Utils.copyPos(widget1, widget2, true); // Also copy constraints
-     */
-    static copyPos(a: GridStackWidget, b: GridStackWidget, doMinMax?: boolean): GridStackWidget;
-    /** true if a and b has same size & position */
-    static samePos(a: GridStackPosition, b: GridStackPosition): boolean;
-    /** given a node, makes sure it's min/max are valid */
-    static sanitizeMinMax(node: GridStackNode): void;
-    /** removes field from the first object if same as the second objects (like diffing) and internal '_' for saving */
-    static removeInternalAndSame(a: unknown, b: unknown): void;
-    /** removes internal fields '_' and default values for saving */
-    static removeInternalForSave(n: GridStackNode, removeEl?: boolean): void;
-    /** return the closest parent (or itself) matching the given class */
-    /** delay calling the given function for given delay, preventing new calls from happening while waiting */
-    static throttle(func: () => void, delay: number): () => void;
-    static removePositioningStyles(el: HTMLElement): void;
-    /** single level clone, returning a new object with same top fields. This will share sub objects and arrays */
-    static clone<T>(obj: T): T;
-    /**
-     * Recursive clone version that returns a full copy, checking for nested objects and arrays ONLY.
-     * Note: this will use as-is any key starting with double __ (and not copy inside) some lib have circular dependencies.
-     */
-    static cloneDeep<T>(obj: T): T;
-    /** deep clone the given HTML node, removing teh unique id field */
-    static cloneNode(el: HTMLElement): HTMLElement;
-    static appendTo(el: HTMLElement, parent: string | HTMLElement): void;
-    static addElStyles(el: HTMLElement, styles: {
-        [prop: string]: string | string[];
-    }): void;
-    static initEvent<T>(e: DragEvent | MouseEvent, info: {
-        type: string;
-        target?: EventTarget;
-    }): T;
-    /** copies the MouseEvent (or convert Touch) properties and sends it as another event to the given target */
-    static simulateMouseEvent(e: MouseEvent | Touch, simulatedType: string, target?: EventTarget): void;
-    /**
-     * defines an element that is used to get the offset and scale from grid transforms
-     * returns the scale and offsets from said element
-    */
-    static getValuesFromTransformedElement(parent: HTMLElement): DragTransform;
-    /** swap the given object 2 field values */
-    static swap(o: unknown, a: string, b: string): void;
-    /** returns true if event is inside the given element rectangle */
-    /** true if the item can be rotated (checking for prop, not space available) */
-    static canBeRotated(n: GridStackNode): boolean;
-}

package/dist/src/utils.js

@@ -1,5 +1,5 @@
 /**
- * utils.ts 12.3.3
+ * utils.ts 12.4.0
  * Copyright (c) 2021-2025 Alain Dumesny - see GridStack root license
  */
 /**
@@ -14,15 +14,15 @@
  * @returns a wrapper function that warns about deprecation
  */
 // eslint-disable-next-line
-export function obsolete(self, f, oldName, newName, rev) {
-    const wrapper = (...args) => {
-        console.warn('gridstack.js: Function `' + oldName + '` is deprecated in ' + rev + ' and has been replaced ' +
-            'with `' + newName + '`. It will be **removed** in a future release');
-        return f.apply(self, args);
-    };
-    wrapper.prototype = f.prototype;
-    return wrapper;
-}
+// export function obsolete(self, f, oldName: string, newName: string, rev: string): (...args: any[]) => any {
+//   const wrapper = (...args) => {
+//     console.warn('gridstack.js: Function `' + oldName + '` is deprecated in ' + rev + ' and has been replaced ' +
+//     'with `' + newName + '`. It will be **removed** in a future release');
+//     return f.apply(self, args);
+//   }
+//   wrapper.prototype = f.prototype;
+//   return wrapper;
+// }
 /**
  * @internal Checks for obsolete grid options and migrates them to new names.
  * Automatically copies old option values to new option names and shows deprecation warnings.
@@ -32,13 +32,13 @@ export function obsolete(self, f, oldName, newName, rev) {
  * @param newName the new option name to use instead
  * @param rev the version when the deprecation was introduced
  */
-export function obsoleteOpts(opts, oldName, newName, rev) {
-    if (opts[oldName] !== undefined) {
-        opts[newName] = opts[oldName];
-        console.warn('gridstack.js: Option `' + oldName + '` is deprecated in ' + rev + ' and has been replaced with `' +
-            newName + '`. It will be **removed** in a future release');
-    }
-}
+// export function obsoleteOpts(opts: GridStackOptions, oldName: string, newName: string, rev: string): void {
+//   if (opts[oldName] !== undefined) {
+//     opts[newName] = opts[oldName];
+//     console.warn('gridstack.js: Option `' + oldName + '` is deprecated in ' + rev + ' and has been replaced with `' +
+//       newName + '`. It will be **removed** in a future release');
+//   }
+// }
 /**
  * @internal Checks for obsolete grid options that have been completely removed.
  * Shows deprecation warnings for options that are no longer supported.
@@ -48,11 +48,11 @@ export function obsoleteOpts(opts, oldName, newName, rev) {
  * @param rev the version when the option was removed
  * @param info additional information about the removal
  */
-export function obsoleteOptsDel(opts, oldName, rev, info) {
-    if (opts[oldName] !== undefined) {
-        console.warn('gridstack.js: Option `' + oldName + '` is deprecated in ' + rev + info);
-    }
-}
+// export function obsoleteOptsDel(opts: GridStackOptions, oldName: string, rev: string, info: string): void {
+//   if (opts[oldName] !== undefined) {
+//     console.warn('gridstack.js: Option `' + oldName + '` is deprecated in ' + rev + info);
+//   }
+// }
 /**
  * @internal Checks for obsolete HTML element attributes and migrates them.
  * Automatically copies old attribute values to new attribute names and shows deprecation warnings.
@@ -62,14 +62,14 @@ export function obsoleteOptsDel(opts, oldName, rev, info) {
  * @param newName the new attribute name to use instead
  * @param rev the version when the deprecation was introduced
  */
-export function obsoleteAttr(el, oldName, newName, rev) {
-    const oldAttr = el.getAttribute(oldName);
-    if (oldAttr !== null) {
-        el.setAttribute(newName, oldAttr);
-        console.warn('gridstack.js: attribute `' + oldName + '`=' + oldAttr + ' is deprecated on this object in ' + rev + ' and has been replaced with `' +
-            newName + '`. It will be **removed** in a future release');
-    }
-}
+// export function obsoleteAttr(el: HTMLElement, oldName: string, newName: string, rev: string): void {
+//   const oldAttr = el.getAttribute(oldName);
+//   if (oldAttr !== null) {
+//     el.setAttribute(newName, oldAttr);
+//     console.warn('gridstack.js: attribute `' + oldName + '`=' + oldAttr + ' is deprecated on this object in ' + rev + ' and has been replaced with `' +
+//       newName + '`. It will be **removed** in a future release');
+//   }
+// }
 /**
  * Collection of utility methods used throughout GridStack.
  * These are general-purpose helper functions for DOM manipulation,
@@ -101,9 +101,15 @@ export class Utils {
             }
             let list = root.querySelectorAll(els);
             if (!list.length && els[0] !== '.' && els[0] !== '#') {
+                // see if mean to be a class
                 list = root.querySelectorAll('.' + els);
-                if (!list.length) {
+                // else if mean to be an id
+                if (!list.length)
                     list = root.querySelectorAll('#' + els);
+                // else see if gs-id attribute
+                if (!list.length) {
+                    const el = root.querySelector(`[gs-id="${els}"]`);
+                    return el ? [el] : [];
                 }
             }
             return Array.from(list);