gridstack 12.2.2 → 12.3.0

package/dist/angular/lib/gridstack.component.d.ts

@@ -1,5 +1,5 @@
 /**
- * gridstack.component.ts 12.2.2
+ * gridstack.component.ts 12.3.0
  * Copyright (c) 2022-2024 Alain Dumesny - see GridStack root license
  */
 import { AfterContentInit, ElementRef, EventEmitter, OnDestroy, OnInit, QueryList, Type, ViewContainerRef, ComponentRef } from '@angular/core';
@@ -8,79 +8,194 @@ import { GridHTMLElement, GridItemHTMLElement, GridStack, GridStackNode, GridSta
 import { NgGridStackNode, NgGridStackWidget } from './types';
 import { GridstackItemComponent } from './gridstack-item.component';
 import * as i0 from "@angular/core";
-/** events handlers emitters signature for different events */
+/**
+ * Event handler callback signatures for different GridStack events.
+ * These types define the structure of data passed to Angular event emitters.
+ */
+/** Callback for general events (enable, disable, etc.) */
 export declare type eventCB = {
     event: Event;
 };
+/** Callback for element-specific events (resize, drag, etc.) */
 export declare type elementCB = {
     event: Event;
     el: GridItemHTMLElement;
 };
+/** Callback for events affecting multiple nodes (change, etc.) */
 export declare type nodesCB = {
     event: Event;
     nodes: GridStackNode[];
 };
+/** Callback for drop events with before/after node state */
 export declare type droppedCB = {
     event: Event;
     previousNode: GridStackNode;
     newNode: GridStackNode;
 };
-/** store element to Ng Class pointer back */
+/**
+ * Extended HTMLElement interface for the grid container.
+ * Stores a back-reference to the Angular component for integration purposes.
+ */
 export interface GridCompHTMLElement extends GridHTMLElement {
+    /** Back-reference to the Angular GridStack component */
     _gridComp?: GridstackComponent;
 }
-/** selector string to runtime Type mapping */
+/**
+ * Mapping of selector strings to Angular component types.
+ * Used for dynamic component creation based on widget selectors.
+ */
 export declare type SelectorToType = {
     [key: string]: Type<Object>;
 };
 /**
- * HTML Component Wrapper for gridstack, in combination with GridstackItemComponent for the items
+ * Angular component wrapper for GridStack.
+ *
+ * This component provides Angular integration for GridStack grids, handling:
+ * - Grid initialization and lifecycle
+ * - Dynamic component creation and management
+ * - Event binding and emission
+ * - Integration with Angular change detection
+ *
+ * Use in combination with GridstackItemComponent for individual grid items.
+ *
+ * @example
+ * ```html
+ * <gridstack [options]="gridOptions" (change)="onGridChange($event)">
+ *   <div empty-content>Drag widgets here</div>
+ * </gridstack>
+ * ```
  */
 export declare class GridstackComponent implements OnInit, AfterContentInit, OnDestroy {
     protected readonly elementRef: ElementRef<GridCompHTMLElement>;
-    /** track list of TEMPLATE (not recommended) grid items so we can sync between DOM and GS internals */
+    /**
+     * List of template-based grid items (not recommended approach).
+     * Used to sync between DOM and GridStack internals when items are defined in templates.
+     * Prefer dynamic component creation instead.
+     */
     gridstackItems?: QueryList<GridstackItemComponent>;
-    /** container to append items dynamically (recommended way) */
+    /**
+     * Container for dynamic component creation (recommended approach).
+     * Used to append grid items programmatically at runtime.
+     */
     container?: ViewContainerRef;
-    /** initial options for creation of the grid */
+    /**
+     * Grid configuration options.
+     * Can be set before grid initialization or updated after grid is created.
+     *
+     * @example
+     * ```typescript
+     * gridOptions: GridStackOptions = {
+     *   column: 12,
+     *   cellHeight: 'auto',
+     *   animate: true
+     * };
+     * ```
+     */
     set options(o: GridStackOptions);
-    /** return the current running options */
+    /** Get the current running grid options */
     get options(): GridStackOptions;
-    /** true while ng-content with 'no-item-content' should be shown when last item is removed from a grid */
+    /**
+     * Controls whether empty content should be displayed.
+     * Set to true to show ng-content with 'empty-content' selector when grid has no items.
+     *
+     * @example
+     * ```html
+     * <gridstack [isEmpty]="gridItems.length === 0">
+     *   <div empty-content>Drag widgets here to get started</div>
+     * </gridstack>
+     * ```
+     */
     isEmpty?: boolean;
-    /** individual list of GridStackEvent callbacks handlers as output
-     * otherwise use this.grid.on('name1 name2 name3', callback) to handle multiple at once
-     * see https://github.com/gridstack/gridstack.js/blob/master/demo/events.js#L4
+    /**
+     * GridStack event emitters for Angular integration.
+     *
+     * These provide Angular-style event handling for GridStack events.
+     * Alternatively, use `this.grid.on('event1 event2', callback)` for multiple events.
      *
-     * Note: camel casing and 'CB' added at the end to prevent @angular-eslint/no-output-native
-     * eg: 'change' would trigger the raw CustomEvent so use different name.
+     * Note: 'CB' suffix prevents conflicts with native DOM events.
+     *
+     * @example
+     * ```html
+     * <gridstack (changeCB)="onGridChange($event)" (droppedCB)="onItemDropped($event)">
+     * </gridstack>
+     * ```
      */
+    /** Emitted when widgets are added to the grid */
     addedCB: EventEmitter<nodesCB>;
+    /** Emitted when grid layout changes */
     changeCB: EventEmitter<nodesCB>;
+    /** Emitted when grid is disabled */
     disableCB: EventEmitter<eventCB>;
+    /** Emitted during widget drag operations */
     dragCB: EventEmitter<elementCB>;
+    /** Emitted when widget drag starts */
     dragStartCB: EventEmitter<elementCB>;
+    /** Emitted when widget drag stops */
     dragStopCB: EventEmitter<elementCB>;
+    /** Emitted when widget is dropped */
     droppedCB: EventEmitter<droppedCB>;
+    /** Emitted when grid is enabled */
     enableCB: EventEmitter<eventCB>;
+    /** Emitted when widgets are removed from the grid */
     removedCB: EventEmitter<nodesCB>;
+    /** Emitted during widget resize operations */
     resizeCB: EventEmitter<elementCB>;
+    /** Emitted when widget resize starts */
     resizeStartCB: EventEmitter<elementCB>;
+    /** Emitted when widget resize stops */
     resizeStopCB: EventEmitter<elementCB>;
-    /** return the native element that contains grid specific fields as well */
+    /**
+     * Get the native DOM element that contains grid-specific fields.
+     * This element has GridStack properties attached to it.
+     */
     get el(): GridCompHTMLElement;
-    /** return the GridStack class */
+    /**
+     * Get the underlying GridStack instance.
+     * Use this to access GridStack API methods directly.
+     *
+     * @example
+     * ```typescript
+     * this.gridComponent.grid.addWidget({x: 0, y: 0, w: 2, h: 1});
+     * ```
+     */
     get grid(): GridStack | undefined;
-    /** ComponentRef of ourself - used by dynamic object to correctly get removed */
+    /**
+     * Component reference for dynamic component removal.
+     * Used internally when this component is created dynamically.
+     */
     ref: ComponentRef<GridstackComponent> | undefined;
     /**
-     * stores the selector -> Type mapping, so we can create items dynamically from a string.
-     * Unfortunately Ng doesn't provide public access to that mapping.
+     * Mapping of component selectors to their types for dynamic creation.
+     *
+     * This enables dynamic component instantiation from string selectors.
+     * Angular doesn't provide public access to this mapping, so we maintain our own.
+     *
+     * @example
+     * ```typescript
+     * GridstackComponent.addComponentToSelectorType([MyWidgetComponent]);
+     * ```
      */
     static selectorToType: SelectorToType;
-    /** add a list of ng Component to be mapped to selector */
+    /**
+     * Register a list of Angular components for dynamic creation.
+     *
+     * @param typeList Array of component types to register
+     *
+     * @example
+     * ```typescript
+     * GridstackComponent.addComponentToSelectorType([
+     *   MyWidgetComponent,
+     *   AnotherWidgetComponent
+     * ]);
+     * ```
+     */
     static addComponentToSelectorType(typeList: Array<Type<Object>>): void;
-    /** return the ng Component selector */
+    /**
+     * Extract the selector string from an Angular component type.
+     *
+     * @param type The component type to get selector from
+     * @returns The component's selector string
+     */
     static getSelector(type: Type<Object>): string;
     protected _options?: GridStackOptions;
     protected _grid?: GridStack;

package/dist/angular/lib/gridstack.module.d.ts

@@ -1,6 +1,29 @@
 import * as i0 from "@angular/core";
 import * as i1 from "./gridstack-item.component";
 import * as i2 from "./gridstack.component";
+/**
+ * @deprecated Use GridstackComponent and GridstackItemComponent as standalone components instead.
+ *
+ * This NgModule is provided for backward compatibility but is no longer the recommended approach.
+ * Import components directly in your standalone components or use the new Angular module structure.
+ *
+ * @example
+ * ```typescript
+ * // Preferred approach - standalone components
+ * @Component({
+ *   selector: 'my-app',
+ *   imports: [GridstackComponent, GridstackItemComponent],
+ *   template: '<gridstack></gridstack>'
+ * })
+ * export class AppComponent {}
+ *
+ * // Legacy approach (deprecated)
+ * @NgModule({
+ *   imports: [GridstackModule]
+ * })
+ * export class AppModule {}
+ * ```
+ */
 export declare class GridstackModule {
     static ɵfac: i0.ɵɵFactoryDeclaration<GridstackModule, never>;
     static ɵmod: i0.ɵɵNgModuleDeclaration<GridstackModule, never, [typeof i1.GridstackItemComponent, typeof i2.GridstackComponent], [typeof i1.GridstackItemComponent, typeof i2.GridstackComponent]>;

package/dist/angular/lib/types.d.ts

@@ -1,24 +1,51 @@
 /**
- * gridstack-item.component.ts 12.2.2
+ * gridstack-item.component.ts 12.3.0
  * Copyright (c) 2025 Alain Dumesny - see GridStack root license
  */
 import { GridStackNode, GridStackOptions, GridStackWidget } from "gridstack";
-/** extends to store Ng Component selector, instead/inAddition to content */
+/**
+ * Extended GridStackWidget interface for Angular integration.
+ * Adds Angular-specific properties for dynamic component creation.
+ */
 export interface NgGridStackWidget extends GridStackWidget {
-    /** Angular tag selector for this component to create at runtime */
+    /** Angular component selector for dynamic creation (e.g., 'my-widget') */
     selector?: string;
-    /** serialized data for the component input fields */
+    /** Serialized data for component @Input() properties */
     input?: NgCompInputs;
-    /** nested grid options */
+    /** Configuration for nested sub-grids */
     subGridOpts?: NgGridStackOptions;
 }
+/**
+ * Extended GridStackNode interface for Angular integration.
+ * Adds component selector for dynamic content creation.
+ */
 export interface NgGridStackNode extends GridStackNode {
+    /** Angular component selector for this node's content */
     selector?: string;
 }
+/**
+ * Extended GridStackOptions interface for Angular integration.
+ * Supports Angular-specific widget definitions and nested grids.
+ */
 export interface NgGridStackOptions extends GridStackOptions {
+    /** Array of Angular widget definitions for initial grid setup */
     children?: NgGridStackWidget[];
+    /** Configuration for nested sub-grids (Angular-aware) */
     subGridOpts?: NgGridStackOptions;
 }
+/**
+ * Type for component input data serialization.
+ * Maps @Input() property names to their values for widget persistence.
+ *
+ * @example
+ * ```typescript
+ * const inputs: NgCompInputs = {
+ *   title: 'My Widget',
+ *   value: 42,
+ *   config: { enabled: true }
+ * };
+ * ```
+ */
 export declare type NgCompInputs = {
     [key: string]: any;
 };

package/dist/angular/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gridstack-angular",
-  "version": "11.1.0",
+  "version": "12.3.0",
   "peerDependencies": {
     "@angular/common": ">=14",
     "@angular/core": ">=14"

package/dist/angular/src/base-widget.ts

@@ -1,30 +1,89 @@
 /**
- * gridstack-item.component.ts 12.2.2
+ * gridstack-item.component.ts 12.3.0
  * Copyright (c) 2022-2024 Alain Dumesny - see GridStack root license
  */
 
 /**
- * Base interface that all widgets need to implement in order for GridstackItemComponent to correctly save/load/delete/..
+ * Abstract base class that all custom widgets should extend.
+ * 
+ * This class provides the interface needed for GridstackItemComponent to:
+ * - Serialize/deserialize widget data
+ * - Save/restore widget state
+ * - Integrate with Angular lifecycle
+ * 
+ * Extend this class when creating custom widgets for dynamic grids.
+ * 
+ * @example
+ * ```typescript
+ * @Component({
+ *   selector: 'my-custom-widget',
+ *   template: '<div>{{data}}</div>'
+ * })
+ * export class MyCustomWidget extends BaseWidget {
+ *   @Input() data: string = '';
+ *   
+ *   serialize() {
+ *     return { data: this.data };
+ *   }
+ * }
+ * ```
  */
 
 import { Injectable } from '@angular/core';
 import { NgCompInputs, NgGridStackWidget } from './types';
 
- @Injectable()
- export abstract class BaseWidget {
+/**
+ * Base widget class for GridStack Angular integration.
+ */
+@Injectable()
+export abstract class BaseWidget {
 
-  /** variable that holds the complete definition of this widgets (with selector,x,y,w,h) */
+  /**
+   * Complete widget definition including position, size, and Angular-specific data.
+   * Populated automatically when the widget is loaded or saved.
+   */
   public widgetItem?: NgGridStackWidget;
 
   /**
-   * REDEFINE to return an object representing the data needed to re-create yourself, other than `selector` already handled.
-   * This should map directly to the @Input() fields of this objects on create, so a simple apply can be used on read
+   * Override this method to return serializable data for this widget.
+   * 
+   * Return an object with properties that map to your component's @Input() fields.
+   * The selector is handled automatically, so only include component-specific data.
+   * 
+   * @returns Object containing serializable component data
+   * 
+   * @example
+   * ```typescript
+   * serialize() {
+   *   return {
+   *     title: this.title,
+   *     value: this.value,
+   *     settings: this.settings
+   *   };
+   * }
+   * ```
    */
   public serialize(): NgCompInputs | undefined  { return; }
 
   /**
-   * REDEFINE this if your widget needs to read from saved data and transform it to create itself - you do this for
-   * things that are not mapped directly into @Input() fields for example.
+   * Override this method to handle widget restoration from saved data.
+   * 
+   * Use this for complex initialization that goes beyond simple @Input() mapping.
+   * The default implementation automatically assigns input data to component properties.
+   * 
+   * @param w The saved widget data including input properties
+   * 
+   * @example
+   * ```typescript
+   * deserialize(w: NgGridStackWidget) {
+   *   super.deserialize(w); // Call parent for basic setup
+   *   
+   *   // Custom initialization logic
+   *   if (w.input?.complexData) {
+   *     this.processComplexData(w.input.complexData);
+   *   }
+   * }
+   * ```
    */
   public deserialize(w: NgGridStackWidget)  {
     // save full description for meta data

package/dist/angular/src/gridstack-item.component.ts

@@ -1,5 +1,5 @@
 /**
- * gridstack-item.component.ts 12.2.2
+ * gridstack-item.component.ts 12.3.0
  * Copyright (c) 2022-2024 Alain Dumesny - see GridStack root license
  */
 
@@ -7,13 +7,34 @@ import { Component, ElementRef, Input, ViewChild, ViewContainerRef, OnDestroy, C
 import { GridItemHTMLElement, GridStackNode } from 'gridstack';
 import { BaseWidget } from './base-widget';
 
-/** store element to Ng Class pointer back */
+/**
+ * Extended HTMLElement interface for grid items.
+ * Stores a back-reference to the Angular component for integration.
+ */
 export interface GridItemCompHTMLElement extends GridItemHTMLElement {
+  /** Back-reference to the Angular GridStackItem component */
   _gridItemComp?: GridstackItemComponent;
 }
 
 /**
- * HTML Component Wrapper for gridstack items, in combination with GridstackComponent for parent grid
+ * Angular component wrapper for individual GridStack items.
+ * 
+ * This component represents a single grid item and handles:
+ * - Dynamic content creation and management
+ * - Integration with parent GridStack component
+ * - Component lifecycle and cleanup
+ * - Widget options and configuration
+ * 
+ * Use in combination with GridstackComponent for the parent grid.
+ * 
+ * @example
+ * ```html
+ * <gridstack>
+ *   <gridstack-item [options]="{x: 0, y: 0, w: 2, h: 1}">
+ *     <my-widget-component></my-widget-component>
+ *   </gridstack-item>
+ * </gridstack>
+ * ```
  */
 @Component({
   selector: 'gridstack-item',
@@ -34,16 +55,37 @@ export interface GridItemCompHTMLElement extends GridItemHTMLElement {
 })
 export class GridstackItemComponent implements OnDestroy {
 
-  /** container to append items dynamically */
+  /**
+   * Container for dynamic component creation within this grid item.
+   * Used to append child components programmatically.
+   */
   @ViewChild('container', { read: ViewContainerRef, static: true}) public container?: ViewContainerRef;
 
-  /** ComponentRef of ourself - used by dynamic object to correctly get removed */
+  /**
+   * Component reference for dynamic component removal.
+   * Used internally when this component is created dynamically.
+   */
   public ref: ComponentRef<GridstackItemComponent> | undefined;
 
-  /** child component so we can save/restore additional data to be saved along */
+  /**
+   * Reference to child widget component for serialization.
+   * Used to save/restore additional data along with grid position.
+   */
   public childWidget: BaseWidget | undefined;
 
-  /** list of options for creating/updating this item */
+  /**
+   * Grid item configuration options.
+   * Defines position, size, and behavior of this grid item.
+   * 
+   * @example
+   * ```typescript
+   * itemOptions: GridStackNode = {
+   *   x: 0, y: 0, w: 2, h: 1,
+   *   noResize: true,
+   *   content: 'Item content'
+   * };
+   * ```
+   */
   @Input() public set options(val: GridStackNode) {
     const grid = this.el.gridstackNode?.grid;
     if (grid) {