@microsoft/fast-element 2.0.1 → 2.2.0

package/dist/esm/observation/arrays.js

@@ -44,6 +44,19 @@ export class Splice {
         return this;
     }
 }
+/**
+ * A sort array indicates new index positions of array items.
+ * @public
+ */
+export class Sort {
+    /**
+     * Creates a sort update.
+     * @param sorted - The updated index of sorted items.
+     */
+    constructor(sorted) {
+        this.sorted = sorted;
+    }
+}
 /**
  * Indicates what level of feature support the splice
  * strategy provides.
@@ -362,7 +375,7 @@ function project(array, changes) {
  * splices needed to represent the change from the old array to the new array.
  * @public
  */
-let defaultSpliceStrategy = Object.freeze({
+let defaultMutationStrategy = Object.freeze({
     support: SpliceStrategySupport.optimized,
     normalize(previous, current, changes) {
         if (previous === void 0) {
@@ -388,7 +401,12 @@ let defaultSpliceStrategy = Object.freeze({
     },
     reverse(array, observer, reverse, args) {
         const result = reverse.apply(array, args);
-        observer.reset(array);
+        array.sorted++;
+        const sortedItems = [];
+        for (let i = array.length - 1; i >= 0; i--) {
+            sortedItems.push(i);
+        }
+        observer.addSort(new Sort(sortedItems));
         return result;
     },
     shift(array, observer, shift, args) {
@@ -400,8 +418,20 @@ let defaultSpliceStrategy = Object.freeze({
         return result;
     },
     sort(array, observer, sort, args) {
+        const map = new Map();
+        for (let i = 0, ii = array.length; i < ii; ++i) {
+            const mapValue = map.get(array[i]) || [];
+            map.set(array[i], [...mapValue, i]);
+        }
         const result = sort.apply(array, args);
-        observer.reset(array);
+        array.sorted++;
+        const sortedItems = [];
+        for (let i = 0, ii = array.length; i < ii; ++i) {
+            const indexs = map.get(array[i]);
+            sortedItems.push(indexs[0]);
+            map.set(array[i], indexs.splice(1));
+        }
+        observer.addSort(new Sort(sortedItems));
         return result;
     },
     splice(array, observer, splice, args) {
@@ -429,13 +459,14 @@ export const SpliceStrategy = Object.freeze({
      * @param strategy - The splice strategy to use.
      */
     setDefaultStrategy(strategy) {
-        defaultSpliceStrategy = strategy;
+        defaultMutationStrategy = strategy;
     },
 });
-function setNonEnumerable(target, property, value) {
+function setNonEnumerable(target, property, value, writable = true) {
     Reflect.defineProperty(target, property, {
         value,
         enumerable: false,
+        writable,
     });
 }
 class DefaultArrayObserver extends SubscriberSet {
@@ -443,9 +474,11 @@ class DefaultArrayObserver extends SubscriberSet {
         super(subject);
         this.oldCollection = void 0;
         this.splices = void 0;
+        this.sorts = void 0;
         this.needsQueue = true;
         this._strategy = null;
         this._lengthObserver = void 0;
+        this._sortObserver = void 0;
         this.call = this.flush;
         setNonEnumerable(subject, "$fastController", this);
     }
@@ -472,6 +505,23 @@ class DefaultArrayObserver extends SubscriberSet {
         }
         return observer;
     }
+    get sortObserver() {
+        let observer = this._sortObserver;
+        if (observer === void 0) {
+            const array = this.subject;
+            this._sortObserver = observer = {
+                sorted: array.sorted,
+                handleChange() {
+                    if (this.sorted !== array.sorted) {
+                        this.sorted = array.sorted;
+                        Observable.notify(observer, "sorted");
+                    }
+                },
+            };
+            this.subscribe(observer);
+        }
+        return observer;
+    }
     subscribe(subscriber) {
         this.flush();
         super.subscribe(subscriber);
@@ -485,6 +535,15 @@ class DefaultArrayObserver extends SubscriberSet {
         }
         this.enqueue();
     }
+    addSort(sort) {
+        if (this.sorts === void 0) {
+            this.sorts = [sort];
+        }
+        else {
+            this.sorts.push(sort);
+        }
+        this.enqueue();
+    }
     reset(oldCollection) {
         this.oldCollection = oldCollection;
         this.enqueue();
@@ -492,14 +551,18 @@ class DefaultArrayObserver extends SubscriberSet {
     flush() {
         var _a;
         const splices = this.splices;
+        const sorts = this.sorts;
         const oldCollection = this.oldCollection;
-        if (splices === void 0 && oldCollection === void 0) {
+        if (splices === void 0 && oldCollection === void 0 && sorts === void 0) {
             return;
         }
         this.needsQueue = true;
         this.splices = void 0;
+        this.sorts = void 0;
         this.oldCollection = void 0;
-        this.notify(((_a = this._strategy) !== null && _a !== void 0 ? _a : defaultSpliceStrategy).normalize(oldCollection, this.subject, splices));
+        sorts !== void 0
+            ? this.notify(sorts)
+            : this.notify(((_a = this._strategy) !== null && _a !== void 0 ? _a : defaultMutationStrategy).normalize(oldCollection, this.subject, splices));
     }
     enqueue() {
         if (this.needsQueue) {
@@ -514,6 +577,7 @@ let enabled = false;
  * @public
  */
 export const ArrayObserver = Object.freeze({
+    sorted: 0,
     /**
      * Enables the array observation mechanism.
      * @remarks
@@ -530,6 +594,7 @@ export const ArrayObserver = Object.freeze({
         const proto = Array.prototype;
         if (!proto.$fastPatch) {
             setNonEnumerable(proto, "$fastPatch", 1);
+            setNonEnumerable(proto, "sorted", 0);
             [
                 proto.pop,
                 proto.push,
@@ -544,7 +609,7 @@ export const ArrayObserver = Object.freeze({
                     const o = this.$fastController;
                     return o === void 0
                         ? method.apply(this, args)
-                        : ((_a = o.strategy) !== null && _a !== void 0 ? _a : defaultSpliceStrategy)[method.name](this, o, method, args);
+                        : ((_a = o.strategy) !== null && _a !== void 0 ? _a : defaultMutationStrategy)[method.name](this, o, method, args);
                 };
             });
         }
@@ -568,3 +633,21 @@ export function lengthOf(array) {
     Observable.track(arrayObserver.lengthObserver, "length");
     return array.length;
 }
+/**
+ * Enables observing the sorted property of an array.
+ * @param array - The array to observe the sorted property of.
+ * @returns The sorted property.
+ * @public
+ */
+export function sortedCount(array) {
+    if (!array) {
+        return 0;
+    }
+    let arrayObserver = array.$fastController;
+    if (arrayObserver === void 0) {
+        ArrayObserver.enable();
+        arrayObserver = Observable.getNotifier(array);
+    }
+    Observable.track(arrayObserver.sortObserver, "sorted");
+    return array.sorted;
+}

package/dist/esm/templating/repeat.js

@@ -112,8 +112,11 @@ export class RepeatBehavior {
         else if (args[0].reset) {
             this.refreshAllViews();
         }
+        else if (args[0].sorted) {
+            this.updateSortedViews(args);
+        }
         else {
-            this.updateViews(args);
+            this.updateSplicedViews(args);
         }
     }
     observeItems(force = false) {
@@ -131,7 +134,27 @@ export class RepeatBehavior {
             newObserver.subscribe(this);
         }
     }
-    updateViews(splices) {
+    updateSortedViews(sorts) {
+        const views = this.views;
+        for (let i = 0, ii = sorts.length; i < ii; ++i) {
+            const sortedItems = sorts[i].sorted.slice();
+            const unsortedItems = sortedItems.slice().sort();
+            for (let j = 0, jj = sortedItems.length; j < jj; ++j) {
+                const sortedIndex = sortedItems.find(value => sortedItems[j] === unsortedItems[value]);
+                if (sortedIndex !== j) {
+                    const removedItems = unsortedItems.splice(sortedIndex, 1);
+                    unsortedItems.splice(j, 0, ...removedItems);
+                    const neighbor = views[j];
+                    const location = neighbor ? neighbor.firstChild : this.location;
+                    views[sortedIndex].remove();
+                    views[sortedIndex].insertBefore(location);
+                    const removedViews = views.splice(sortedIndex, 1);
+                    views.splice(j, 0, ...removedViews);
+                }
+            }
+        }
+    }
+    updateSplicedViews(splices) {
         const views = this.views;
         const bindView = this.bindView;
         const items = this.items;

package/dist/fast-element.api.json

@@ -426,6 +426,52 @@
           "name": "ArrayObserver",
           "preserveMemberOrder": false,
           "members": [
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@microsoft/fast-element!ArrayObserver#addSort:member(1)",
+              "docComment": "/**\n * Adds a sort to the list of changes.\n *\n * @param sort - The sort to add.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "addSort(sort: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Sort",
+                  "canonicalReference": "@microsoft/fast-element!Sort:class"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": false,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "sort",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "name": "addSort"
+            },
             {
               "kind": "MethodSignature",
               "canonicalReference": "@microsoft/fast-element!ArrayObserver#addSplice:member(1)",
@@ -573,6 +619,34 @@
               ],
               "name": "reset"
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/fast-element!ArrayObserver#sortObserver:member",
+              "docComment": "/**\n * The sort observer for the array.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly sortObserver: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "SortObserver",
+                  "canonicalReference": "@microsoft/fast-element!SortObserver:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "sortObserver",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@microsoft/fast-element!ArrayObserver#strategy:member",
@@ -629,7 +703,7 @@
             },
             {
               "kind": "Content",
-              "text": "<{\n    readonly enable: () => void;\n}>"
+              "text": "<{\n    readonly sorted: 0;\n    readonly enable: () => void;\n}>"
             }
           ],
           "fileUrlPath": "dist/dts/observation/arrays.d.ts",
@@ -5136,7 +5210,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@microsoft/fast-element!ElementController.forCustomElement:member(1)",
-              "docComment": "/**\n * Locates or creates a controller for the specified element.\n *\n * @remarks\n *\n * The specified element must have a {@link FASTElementDefinition} registered either through the use of the {@link customElement} decorator or a call to `FASTElement.define`.\n *\n * @param element - The element to return the controller for.\n */\n",
+              "docComment": "/**\n * Locates or creates a controller for the specified element.\n *\n * @remarks\n *\n * The specified element must have a {@link FASTElementDefinition} registered either through the use of the {@link customElement} decorator or a call to `FASTElement.define`.\n *\n * @param element - The element to return the controller for.\n *\n * @param override - Reset the controller even if one has been defined.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -5147,6 +5221,14 @@
                   "text": "HTMLElement",
                   "canonicalReference": "!HTMLElement:interface"
                 },
+                {
+                  "kind": "Content",
+                  "text": ", override?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
                 {
                   "kind": "Content",
                   "text": "): "
@@ -5163,8 +5245,8 @@
               ],
               "isStatic": true,
               "returnTypeTokenRange": {
-                "startIndex": 3,
-                "endIndex": 4
+                "startIndex": 5,
+                "endIndex": 6
               },
               "releaseTag": "Public",
               "isProtected": false,
@@ -5177,6 +5259,14 @@
                     "endIndex": 2
                   },
                   "isOptional": false
+                },
+                {
+                  "parameterName": "override",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": true
                 }
               ],
               "isOptional": false,
@@ -9154,7 +9244,7 @@
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "readonly template?: "
+                  "text": "template?: "
                 },
                 {
                   "kind": "Reference",
@@ -9166,7 +9256,7 @@
                   "text": ";"
                 }
               ],
-              "isReadonly": true,
+              "isReadonly": false,
               "isOptional": true,
               "releaseTag": "Public",
               "name": "template",
@@ -16485,6 +16575,15 @@
                   "kind": "Content",
                   "text": "[] | "
                 },
+                {
+                  "kind": "Reference",
+                  "text": "Sort",
+                  "canonicalReference": "@microsoft/fast-element!Sort:class"
+                },
+                {
+                  "kind": "Content",
+                  "text": "[] | "
+                },
                 {
                   "kind": "Reference",
                   "text": "ExpressionObserver",
@@ -16505,8 +16604,8 @@
               ],
               "isStatic": false,
               "returnTypeTokenRange": {
-                "startIndex": 7,
-                "endIndex": 8
+                "startIndex": 9,
+                "endIndex": 10
               },
               "releaseTag": "Public",
               "isProtected": false,
@@ -16524,7 +16623,7 @@
                   "parameterName": "args",
                   "parameterTypeTokenRange": {
                     "startIndex": 3,
-                    "endIndex": 6
+                    "endIndex": 8
                   },
                   "isOptional": false
                 }
@@ -17462,6 +17561,204 @@
             }
           ]
         },
+        {
+          "kind": "Class",
+          "canonicalReference": "@microsoft/fast-element!Sort:class",
+          "docComment": "/**\n * A sort array indicates new index positions of array items.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare class Sort "
+            }
+          ],
+          "fileUrlPath": "dist/dts/observation/arrays.d.ts",
+          "releaseTag": "Public",
+          "isAbstract": false,
+          "name": "Sort",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "Constructor",
+              "canonicalReference": "@microsoft/fast-element!Sort:constructor(1)",
+              "docComment": "/**\n * Creates a sort update.\n *\n * @param sorted - The updated index of sorted items.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "constructor(sorted?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number[] | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ");"
+                }
+              ],
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "sorted",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": true
+                }
+              ]
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@microsoft/fast-element!Sort#sorted:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "sorted?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number[] | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "sorted",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            }
+          ],
+          "implementsTokenRanges": []
+        },
+        {
+          "kind": "Function",
+          "canonicalReference": "@microsoft/fast-element!sortedCount:function(1)",
+          "docComment": "/**\n * Enables observing the sorted property of an array.\n *\n * @param array - The array to observe the sorted property of.\n *\n * @returns The sorted property.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function sortedCount<T>(array: "
+            },
+            {
+              "kind": "Content",
+              "text": "readonly T[]"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Content",
+              "text": "number"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/dts/observation/arrays.d.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 4
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "array",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            }
+          ],
+          "typeParameters": [
+            {
+              "typeParameterName": "T",
+              "constraintTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "name": "sortedCount"
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@microsoft/fast-element!SortObserver:interface",
+          "docComment": "/**\n * Observes array sort.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface SortObserver extends "
+            },
+            {
+              "kind": "Reference",
+              "text": "Subscriber",
+              "canonicalReference": "@microsoft/fast-element!Subscriber:interface"
+            },
+            {
+              "kind": "Content",
+              "text": " "
+            }
+          ],
+          "fileUrlPath": "dist/dts/observation/arrays.d.ts",
+          "releaseTag": "Public",
+          "name": "SortObserver",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/fast-element!SortObserver#sorted:member",
+              "docComment": "/**\n * The sorted times on the observed array, this should be incremented every time an item in the array changes location.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "sorted: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "sorted",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": [
+            {
+              "startIndex": 1,
+              "endIndex": 2
+            }
+          ]
+        },
         {
           "kind": "TypeAlias",
           "canonicalReference": "@microsoft/fast-element!SourceLifetime:type",