@microsoft/fast-element 2.0.0 → 2.1.0

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",
@@ -1286,7 +1360,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@microsoft/fast-element!AttributeDefinition#setValue:member(1)",
-              "docComment": "/**\n * Sets the value of the attribute/property on the source element.\n *\n * @param source - The source element to access.\n *\n * @param value - The value to set the attribute/property to.\n */\n",
+              "docComment": "/**\n * Sets the value of the attribute/property on the source element.\n *\n * @param source - The source element to access.\n *\n * @param newValue - The value to set the attribute/property to.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -16485,6 +16559,15 @@
                   "kind": "Content",
                   "text": "[] | "
                 },
+                {
+                  "kind": "Reference",
+                  "text": "Sort",
+                  "canonicalReference": "@microsoft/fast-element!Sort:class"
+                },
+                {
+                  "kind": "Content",
+                  "text": "[] | "
+                },
                 {
                   "kind": "Reference",
                   "text": "ExpressionObserver",
@@ -16505,8 +16588,8 @@
               ],
               "isStatic": false,
               "returnTypeTokenRange": {
-                "startIndex": 7,
-                "endIndex": 8
+                "startIndex": 9,
+                "endIndex": 10
               },
               "releaseTag": "Public",
               "isProtected": false,
@@ -16524,7 +16607,7 @@
                   "parameterName": "args",
                   "parameterTypeTokenRange": {
                     "startIndex": 3,
-                    "endIndex": 6
+                    "endIndex": 8
                   },
                   "isOptional": false
                 }
@@ -17462,6 +17545,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",

package/dist/fast-element.debug.js

@@ -8,7 +8,7 @@ if (globalThis.FAST === void 0) {
 }
 const FAST$1 = globalThis.FAST;
 const debugMessages = {
-    [1101 /* needsArrayObservation */]: "Must call enableArrayObservation before observing arrays.",
+    [1101 /* needsArrayObservation */]: "Must call ArrayObserver.enable() before observing arrays.",
     [1201 /* onlySetDOMPolicyOnce */]: "The DOM Policy can only be set once.",
     [1202 /* bindingInnerHTMLRequiresTrustedTypes */]: "To bind innerHTML, you must use a TrustedTypesPolicy.",
     [1203 /* twoWayBindingRequiresObservables */]: "View=>Model update skipped. To use twoWay binding, the target property must be observable.",
@@ -1299,6 +1299,19 @@ class Splice {
         return this;
     }
 }
+/**
+ * A sort array indicates new index positions of array items.
+ * @public
+ */
+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.
@@ -1617,7 +1630,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) {
@@ -1643,7 +1656,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) {
@@ -1655,8 +1673,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) {
@@ -1684,13 +1714,14 @@ 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 {
@@ -1698,9 +1729,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);
     }
@@ -1727,6 +1760,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);
@@ -1740,6 +1790,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();
@@ -1747,14 +1806,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) {
@@ -1769,6 +1832,7 @@ let enabled = false;
  * @public
  */
 const ArrayObserver = Object.freeze({
+    sorted: 0,
     /**
      * Enables the array observation mechanism.
      * @remarks
@@ -1785,6 +1849,7 @@ const ArrayObserver = Object.freeze({
         const proto = Array.prototype;
         if (!proto.$fastPatch) {
             setNonEnumerable(proto, "$fastPatch", 1);
+            setNonEnumerable(proto, "sorted", 0);
             [
                 proto.pop,
                 proto.push,
@@ -1799,7 +1864,7 @@ 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);
                 };
             });
         }
@@ -1823,6 +1888,24 @@ 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
+ */
+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;
+}
 
 /**
  * Captures a binding expression along with related information and capabilities.
@@ -3927,8 +4010,11 @@ 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) {
@@ -3946,7 +4032,27 @@ 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;
@@ -4403,13 +4509,11 @@ const booleanConverter = {
         return value ? "true" : "false";
     },
     fromView(value) {
-        return value === null ||
+        return !(value === null ||
             value === void 0 ||
             value === "false" ||
             value === false ||
-            value === 0
-            ? false
-            : true;
+            value === 0);
     },
 };
 /**
@@ -4481,7 +4585,7 @@ class AttributeDefinition {
     /**
      * Sets the value of the attribute/property on the source element.
      * @param source - The source element to access.
-     * @param value - The value to set the attribute/property to.
+     * @param newValue - The value to set the attribute/property to.
      */
     setValue(source, newValue) {
         const oldValue = source[this.fieldName];
@@ -5919,4 +6023,4 @@ function customElement(nameOrDef) {
 
 DOM.setPolicy(DOMPolicy.create());
 
-export { ArrayObserver, AttributeConfiguration, AttributeDefinition, Binding, CSSBindingDirective, CSSDirective, ChildrenDirective, Compiler, DOM, DOMAspect, ElementController, ElementStyles, ExecutionContext, FAST, FASTElement, FASTElementDefinition, HTMLBindingDirective, HTMLDirective, HTMLView, HydratableElementController, HydrationBindingError, InlineTemplateDirective, Markup, NodeObservationDirective, Observable, Parser, PropertyChangeNotifier, RefDirective, RenderBehavior, RenderDirective, RepeatBehavior, RepeatDirective, SlottedDirective, SourceLifetime, Splice, SpliceStrategy, SpliceStrategySupport, StatelessAttachedAttributeDirective, SubscriberSet, Updates, ViewTemplate, attr, booleanConverter, children, css, cssDirective, customElement, elements, emptyArray, html, htmlDirective, lengthOf, listener, normalizeBinding$1 as normalizeBinding, nullableBooleanConverter, nullableNumberConverter, observable, oneTime, oneWay, ref, render, repeat, slotted, volatile, when };
+export { ArrayObserver, AttributeConfiguration, AttributeDefinition, Binding, CSSBindingDirective, CSSDirective, ChildrenDirective, Compiler, DOM, DOMAspect, ElementController, ElementStyles, ExecutionContext, FAST, FASTElement, FASTElementDefinition, HTMLBindingDirective, HTMLDirective, HTMLView, HydratableElementController, HydrationBindingError, InlineTemplateDirective, Markup, NodeObservationDirective, Observable, Parser, PropertyChangeNotifier, RefDirective, RenderBehavior, RenderDirective, RepeatBehavior, RepeatDirective, SlottedDirective, Sort, SourceLifetime, Splice, SpliceStrategy, SpliceStrategySupport, StatelessAttachedAttributeDirective, SubscriberSet, Updates, ViewTemplate, attr, booleanConverter, children, css, cssDirective, customElement, elements, emptyArray, html, htmlDirective, lengthOf, listener, normalizeBinding$1 as normalizeBinding, nullableBooleanConverter, nullableNumberConverter, observable, oneTime, oneWay, ref, render, repeat, slotted, sortedCount, volatile, when };