gridstack 8.1.0 → 8.1.2

package/angular/projects/demo/src/app/ngFor.ts

@@ -0,0 +1,131 @@
+/**
+ * Example using Angular ngFor to loop through items and create DOM items
+ */
+
+import { Component, AfterViewInit, Input, ViewChildren, QueryList, ElementRef } from '@angular/core';
+import { GridItemHTMLElement, GridStack, GridStackNode, GridStackWidget, Utils } from 'gridstack';
+
+// unique ids sets for each item for correct ngFor updating
+let ids = 1;
+
+@Component({
+  selector: "angular-ng-for-test",
+  template: `
+    <p><b>ngFor</b>: Example using Angular ngFor to loop through items and create DOM items. This track changes made to the array of items, waits for DOM rendering, then update GS</p>
+    <button (click)="add()">add item</button>
+    <button (click)="delete()">remove item</button>
+    <button (click)="modify()">modify item</button>
+    <button (click)="newLayout()">new layout</button>
+    <div class="grid-stack">
+      <!-- using angular templating to create DOM, otherwise an easier way is to simply call grid.load(items)
+      NOTE: this example is NOT complete as there are many more properties than listed (minW, maxW, etc....)
+      -->
+      <div *ngFor="let n of items; trackBy: identify"
+        class="grid-stack-item"
+        [attr.gs-id]="n.id"
+        [attr.gs-x]="n.x"
+        [attr.gs-y]="n.y"
+        [attr.gs-w]="n.w"
+        [attr.gs-h]="n.h"
+        #gridStackItem
+      >
+        <div class="grid-stack-item-content">item {{ n.id }}</div>
+      </div>
+    </div>
+  `,
+  // gridstack.min.css and other custom styles should be included in global styles.scss or here
+})
+export class AngularNgForTestComponent implements AfterViewInit {
+  /** list of HTML items that we track to know when the DOM has been updated to make/remove GS widgets */
+  @ViewChildren("gridStackItem") gridstackItems!: QueryList<ElementRef<GridItemHTMLElement>>;
+
+  /** set the items to display. */
+  @Input() public set items(list: GridStackWidget[]) {
+    this._items = list || [];
+    this._items.forEach(w => w.id = w.id || String(ids++)); // make sure a unique id is generated for correct ngFor loop update
+  }
+  public get items(): GridStackWidget[] { return this._items}
+
+  private grid!: GridStack;
+  public _items!: GridStackWidget[];
+
+  constructor() {
+    this.items = [
+      {x: 0, y: 0},
+      {x: 1, y: 1},
+      {x: 2, y: 2},
+    ];
+  }
+
+  // wait until after DOM is ready to init gridstack - can't be ngOnInit() as angular ngFor needs to run first!
+  public ngAfterViewInit() {
+    this.grid = GridStack.init({
+      margin: 5,
+      float: true,
+    })
+    .on('change added', (event: Event, nodes: GridStackNode[]) => this.onChange(nodes));
+
+    // sync initial actual valued rendered (in case init() had to merge conflicts)
+    this.onChange();
+
+    /**
+     * this is called when the list of items changes - get a list of nodes and
+     * update the layout accordingly (which will take care of adding/removing items changed by Angular)
+     */
+    this.gridstackItems.changes.subscribe(() => {
+      const layout: GridStackWidget[] = [];
+      this.gridstackItems.forEach(ref => {
+        const n = ref.nativeElement.gridstackNode || this.grid.makeWidget(ref.nativeElement).gridstackNode;
+        if (n) layout.push(n);
+      });
+      this.grid.load(layout); // efficient that does diffs only
+    })
+  }
+
+  /** Optional: called when given widgets are changed (moved/resized/added) - update our list to match.
+   * Note this is not strictly necessary as demo works without this
+   */
+  public onChange(list = this.grid.engine.nodes) {
+    setTimeout(() => // prevent new 'added' items from ExpressionChangedAfterItHasBeenCheckedError. TODO: find cleaner way to sync outside Angular change detection ?
+      list.forEach(n => {
+        const item = this._items.find(i => i.id === n.id);
+        if (item) Utils.copyPos(item, n);
+      })
+    , 0);
+  }
+
+  /**
+   * CRUD operations
+   */
+  public add() {
+    // new array isn't required as Angular seem to detect changes to content
+    // this.items = [...this.items, { x:3, y:0, w:3, id:String(ids++) }];
+    this.items.push({ x:3, y:0, w:3, id:String(ids++) });
+  }
+
+  public delete() {
+    this.items.pop();
+  }
+
+  public modify() {
+    // this will only update the DOM attr (from the ngFor loop in our template above)
+    // but not trigger gridstackItems.changes for GS to auto-update, so call GS update() instead
+    // this.items[0].w = 2;
+    const n = this.grid.engine.nodes[0];
+    if (n?.el) this.grid.update(n.el, {w:3});
+  }
+
+  public newLayout() {
+    this.items = [ // test updating existing and creating new one
+      {x:0, y:1, id:'1'},
+      {x:1, y:1, id:'2'},
+      // {x:2, y:1, id:3}, // delete item
+      {x:3, y:0, w:3}, // new item
+    ];
+  }
+
+  // ngFor unique node id to have correct match between our items used and GS
+  identify(index: number, w: GridStackWidget) {
+    return w.id;
+  }
+}

package/angular/projects/demo/src/app/ngFor_cmd.ts

@@ -0,0 +1,106 @@
+/**
+ * Example using Angular ngFor to loop through items and create DOM items - this uses a custom command.
+ * NOTE: see the simpler and better (tracks all changes) angular-ng-for-test
+ */
+
+import { Component, AfterViewInit, Input, ViewChildren, QueryList, ElementRef } from '@angular/core';
+import { Subject, zip } from "rxjs";
+
+import { GridItemHTMLElement, GridStack, GridStackWidget } from 'gridstack';
+
+@Component({
+  selector: "angular-ng-for-cmd-test",
+  template: `
+    <p><b>ngFor CMD</b>: Example using Angular ngFor to loop through items, but uses an explicity command to let us update GS (see automatic better way)</p>
+    <button (click)="add()">add item</button>
+    <button (click)="delete()">remove item</button>
+    <button (click)="modify()">modify item</button>
+    <div class="grid-stack">
+      <!-- using angular templating to create DOM, otherwise an easier way is to simply call grid.load(items) -->
+      <div
+        *ngFor="let n of items; let i = index; trackBy: identify"
+        [id]="i"
+        class="grid-stack-item"
+        [attr.gs-x]="n.x"
+        [attr.gs-y]="n.y"
+        [attr.gs-w]="n.w"
+        [attr.gs-h]="n.h"
+        #gridStackItem
+      >
+        <div class="grid-stack-item-content">item {{ i }}</div>
+      </div>
+    </div>
+  `,
+  // gridstack.min.css and other custom styles should be included in global styles.scss or here
+})
+export class AngularNgForCmdTestComponent implements AfterViewInit {
+  /** list of HTML items that we track to know when the DOM has been updated to make/remove GS widgets */
+  @ViewChildren("gridStackItem") gridstackItems!: QueryList<ElementRef<GridItemHTMLElement>>;
+
+  /** set the items to display. */
+  @Input() public items: GridStackWidget[] = [
+    {x: 0, y: 0},
+    {x: 1, y: 1},
+    {x: 2, y: 2},
+  ];
+
+  private grid!: GridStack;
+  private widgetToMake: Subject<{
+    action: "add" | "remove" | "update";
+    id: number;
+  }> = new Subject(); // consider to use a state management like ngrx component store to do this
+
+  constructor() {}
+
+  // wait until after DOM is ready to init gridstack - can't be ngOnInit() as angular ngFor needs to run first!
+  public ngAfterViewInit() {
+    this.grid = GridStack.init({
+      margin: 5,
+      float: true,
+    });
+
+    // To sync dom manipulation done by Angular and widget manipulation done by gridstack we need to zip the observables
+    zip(this.gridstackItems.changes, this.widgetToMake).subscribe(
+      ([changedWidget, widgetToMake]) => {
+        if (widgetToMake.action === "add") {
+          this.grid.makeWidget(`#${widgetToMake.id}`);
+        } else if (widgetToMake.action === "remove") {
+          const id = String(widgetToMake.id);
+          // Note: DOM element has been removed by Angular already so look for it through the engine node list
+          const removeEl = this.grid.engine.nodes.find((n) => n.el?.id === id)?.el;
+          if (removeEl) this.grid.removeWidget(removeEl);
+        }
+      }
+    );
+
+    // TODO: the problem with this code is that our items list does NOT reflect changes made by GS (user directly changing,
+    // or conflict during initial layout) and believe the other ngFor example (which does track changes) is also cleaner
+    // as it doesn't require user creating special action commands nor track 'both' changes using zip().
+    // TODO: identify() uses index which is not guaranteed to match between invocations (insert/delete in
+    // middle of list instead of end as demo does)
+  }
+
+  /**
+   * CRUD operations
+   */
+  public add() {
+    this.items = [...this.items, { x: 3, y: 0, w: 3 }];
+    this.widgetToMake.next({ action: "add", id: this.items.length - 1 });
+  }
+
+  public delete() {
+    this.items.pop();
+    this.widgetToMake.next({ action: "remove", id: this.items.length });
+  }
+
+  // a change of a widget doesn´t change to amount of items in ngFor therefore we don´t need to do it through the zip function above
+  public modify() {
+    const updateEl = this.grid.getGridItems().find((el) => el.id === `${0}`);
+    this.grid.update(updateEl!, { w: 2 });
+  }
+
+  // ngFor lookup indexing
+  identify(index: number) {
+    return index;
+  }
+}

package/angular/projects/demo/src/app/simple.ts

@@ -0,0 +1,46 @@
+/**
+ * Simplest Angular Example using GridStack API directly
+ */
+ import { Component, OnInit } from '@angular/core';
+
+ import { GridStack, GridStackWidget } from 'gridstack';
+
+ @Component({
+   selector: 'angular-simple-test',
+   template: `
+    <p><b>SIMPLEST</b>: angular example using GridStack API directly, so not really using any angular construct per say other than waiting for DOM rendering</p>
+     <button (click)="add()">add item</button>
+     <button (click)="delete()">remove item</button>
+     <button (click)="change()">modify item</button>
+     <div class="grid-stack"></div>
+     `,
+   // gridstack.min.css and other custom styles should be included in global styles.scss
+ })
+ export class AngularSimpleComponent implements OnInit {
+   public items: GridStackWidget[] = [
+     { x: 0, y: 0, w: 9, h: 6, content: '0' },
+     { x: 9, y: 0, w: 3, h: 3, content: '1' },
+     { x: 9, y: 3, w: 3, h: 3, content: '2' },
+   ];
+   private grid!: GridStack;
+
+   constructor() {}
+
+   // simple div above doesn't require Angular to run, so init gridstack here
+   public ngOnInit() {
+     this.grid = GridStack.init({
+       cellHeight: 70,
+     })
+     .load(this.items); // and load our content directly (will create DOM)
+   }
+
+   public add() {
+     this.grid.addWidget({w: 3, content: 'new content'});
+   }
+   public delete() {
+     this.grid.removeWidget(this.grid.engine.nodes[0].el!);
+   }
+   public change() {
+    this.grid.update(this.grid.engine.nodes[0].el!, {w: 1});
+   }
+ }

package/angular/projects/demo/src/environments/environment.prod.ts

@@ -0,0 +1,3 @@
+export const environment = {
+  production: true
+};

package/angular/projects/demo/src/environments/environment.ts

@@ -0,0 +1,16 @@
+// This file can be replaced during build by using the `fileReplacements` array.
+// `ng build` replaces `environment.ts` with `environment.prod.ts`.
+// The list of file replacements can be found in `angular.json`.
+
+export const environment = {
+  production: false
+};
+
+/*
+ * For easier debugging in development mode, you can import the following file
+ * to ignore zone related error stack frames such as `zone.run`, `zoneDelegate.invokeTask`.
+ *
+ * This import should be commented out in production mode because it will have a negative impact
+ * on performance if an error is thrown.
+ */
+// import 'zone.js/plugins/zone-error';  // Included with Angular CLI.

package/angular/projects/demo/src/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Demo</title>
+  <base href="/">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="icon" type="image/x-icon" href="favicon.ico">
+</head>
+<body>
+  <app-root></app-root>
+</body>
+</html>

package/angular/projects/demo/src/main.ts

@@ -0,0 +1,12 @@
+import { enableProdMode } from '@angular/core';
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
+import { AppModule } from './app/app.module';
+import { environment } from './environments/environment';
+
+if (environment.production) {
+  enableProdMode();
+}
+
+platformBrowserDynamic().bootstrapModule(AppModule)
+  .catch(err => console.error(err));

package/angular/projects/demo/src/polyfills.ts

@@ -0,0 +1,53 @@
+/**
+ * This file includes polyfills needed by Angular and is loaded before the app.
+ * You can add your own extra polyfills to this file.
+ *
+ * This file is divided into 2 sections:
+ *   1. Browser polyfills. These are applied before loading ZoneJS and are sorted by browsers.
+ *   2. Application imports. Files imported after ZoneJS that should be loaded before your main
+ *      file.
+ *
+ * The current setup is for so-called "evergreen" browsers; the last versions of browsers that
+ * automatically update themselves. This includes recent versions of Safari, Chrome (including
+ * Opera), Edge on the desktop, and iOS and Chrome on mobile.
+ *
+ * Learn more in https://angular.io/guide/browser-support
+ */
+
+/***************************************************************************************************
+ * BROWSER POLYFILLS
+ */
+
+/**
+ * By default, zone.js will patch all possible macroTask and DomEvents
+ * user can disable parts of macroTask/DomEvents patch by setting following flags
+ * because those flags need to be set before `zone.js` being loaded, and webpack
+ * will put import in the top of bundle, so user need to create a separate file
+ * in this directory (for example: zone-flags.ts), and put the following flags
+ * into that file, and then add the following code before importing zone.js.
+ * import './zone-flags';
+ *
+ * The flags allowed in zone-flags.ts are listed here.
+ *
+ * The following flags will work for all browsers.
+ *
+ * (window as any).__Zone_disable_requestAnimationFrame = true; // disable patch requestAnimationFrame
+ * (window as any).__Zone_disable_on_property = true; // disable patch onProperty such as onclick
+ * (window as any).__zone_symbol__UNPATCHED_EVENTS = ['scroll', 'mousemove']; // disable patch specified eventNames
+ *
+ *  in IE/Edge developer tools, the addEventListener will also be wrapped by zone.js
+ *  with the following flag, it will bypass `zone.js` patch for IE/Edge
+ *
+ *  (window as any).__Zone_enable_cross_context_check = true;
+ *
+ */
+
+/***************************************************************************************************
+ * Zone JS is required by default for Angular itself.
+ */
+import 'zone.js';  // Included with Angular CLI.
+
+
+/***************************************************************************************************
+ * APPLICATION IMPORTS
+ */

package/angular/projects/demo/src/styles.css

@@ -0,0 +1,4 @@
+/* re-use existing demo css file we already use for the plain demos - that include gridstack.css which is required */
+@import "../../../../demo/demo.css";
+/* required file for gridstack 2-11 column */
+@import "../../../../dist/gridstack-extra.css";

package/angular/projects/demo/src/test.ts

@@ -0,0 +1,26 @@
+// This file is required by karma.conf.js and loads recursively all the .spec and framework files
+
+import 'zone.js/testing';
+import { getTestBed } from '@angular/core/testing';
+import {
+  BrowserDynamicTestingModule,
+  platformBrowserDynamicTesting
+} from '@angular/platform-browser-dynamic/testing';
+
+declare const require: {
+  context(path: string, deep?: boolean, filter?: RegExp): {
+    <T>(id: string): T;
+    keys(): string[];
+  };
+};
+
+// First, initialize the Angular testing environment.
+getTestBed().initTestEnvironment(
+  BrowserDynamicTestingModule,
+  platformBrowserDynamicTesting(),
+);
+
+// Then we find all the tests.
+const context = require.context('./', true, /\.spec\.ts$/);
+// And load the modules.
+context.keys().forEach(context);

package/angular/projects/demo/tsconfig.app.json

@@ -0,0 +1,15 @@
+/* To learn more about this file see: https://angular.io/config/tsconfig. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/app",
+    "types": []
+  },
+  "files": [
+    "src/main.ts",
+    "src/polyfills.ts"
+  ],
+  "include": [
+    "src/**/*.d.ts"
+  ]
+}

package/angular/projects/demo/tsconfig.spec.json

@@ -0,0 +1,18 @@
+/* To learn more about this file see: https://angular.io/config/tsconfig. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/spec",
+    "types": [
+      "jasmine"
+    ]
+  },
+  "files": [
+    "src/test.ts",
+    "src/polyfills.ts"
+  ],
+  "include": [
+    "src/**/*.spec.ts",
+    "src/**/*.d.ts"
+  ]
+}

package/angular/projects/lib/README.md

@@ -0,0 +1,24 @@
+# Gs
+
+This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 14.2.0.
+
+## Code scaffolding
+
+Run `ng generate component component-name --project gs` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project gs`.
+> Note: Don't forget to add `--project gs` or else it will be added to the default project in your `angular.json` file. 
+
+## Build
+
+Run `ng build gs` to build the project. The build artifacts will be stored in the `dist/` directory.
+
+## Publishing
+
+After building your library with `ng build gs`, go to the dist folder `cd dist/gs` and run `npm publish`.
+
+## Running unit tests
+
+Run `ng test gs` to execute the unit tests via [Karma](https://karma-runner.github.io).
+
+## Further help
+
+To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.

package/angular/projects/lib/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../../dist/angular",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  }
+}

package/angular/projects/lib/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "gridstack-angular",
+  "version": "8.1.2",
+  "peerDependencies": {
+    "@angular/common": "^14.2.0",
+    "@angular/core": "^14.2.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  }
+}

package/angular/projects/lib/src/lib/gridstack-item.component.ts

@@ -0,0 +1,70 @@
+/**
+ * gridstack-item.component.ts 8.1.2
+ * Copyright (c) 2022 Alain Dumesny - see GridStack root license
+ */
+
+import { Component, ElementRef, Input, ViewChild, ViewContainerRef, OnDestroy } from '@angular/core';
+import { GridItemHTMLElement, GridStackNode } from 'gridstack';
+
+/** store element to Ng Class pointer back */
+export interface GridItemCompHTMLElement extends GridItemHTMLElement {
+  _gridItemComp?: GridstackItemComponent;
+}
+
+/**
+ * HTML Component Wrapper for gridstack items, in combination with GridstackComponent for parent grid
+ */
+@Component({
+  selector: 'gridstack-item',
+  template: `
+    <div class="grid-stack-item-content">
+      <!-- where dynamic items go based on component types, or sub-grids, etc...) -->
+      <ng-template #container></ng-template>
+      <!-- any static (defined in dom) content goes here -->
+      <ng-content></ng-content>
+      <!-- fallback HTML content from GridStackWidget content field if used instead -->
+      {{options.content}}
+    </div>`,
+  styles: [`
+    :host { display: block; }
+  `],
+  // changeDetection: ChangeDetectionStrategy.OnPush, // IFF you want to optimize and control when ChangeDetection needs to happen...
+})
+export class GridstackItemComponent implements OnDestroy {
+
+  /** container to append items dynamically */
+  @ViewChild('container', { read: ViewContainerRef, static: true}) public container?: ViewContainerRef;
+
+  /** list of options for creating/updating this item */
+  @Input() public set options(val: GridStackNode) {
+    if (this.el.gridstackNode?.grid) {
+      // already built, do an update...
+      this.el.gridstackNode.grid.update(this.el, val);
+    } else {
+      // store our custom element in options so we can update it and not re-create a generic div!
+      this._options = {...val, el: this.el};
+    }
+  }
+  /** return the latest grid options (from GS once built, otherwise initial values) */
+  public get options(): GridStackNode {
+    return this.el.gridstackNode || this._options || {el: this.el};
+  }
+
+  private _options?: GridStackNode;
+
+  /** return the native element that contains grid specific fields as well */
+  public get el(): GridItemCompHTMLElement { return this.elementRef.nativeElement; }
+
+  /** clears the initial options now that we've built */
+  public clearOptions() {
+    delete this._options;
+  }
+
+  constructor(private readonly elementRef: ElementRef<GridItemHTMLElement>) {
+    this.el._gridItemComp = this;
+  }
+
+  public ngOnDestroy(): void {
+    delete this.el._gridItemComp;
+  }
+}