@microsoft/fast-element 2.0.0 → 2.1.0

package/ARCHITECTURE_FASTELEMENT.md

@@ -0,0 +1,63 @@
+# FASTElement
+
+The `FASTElement` is our extension of the `HTMLElement`. As such it leverages the lifecycles but also requires additional setup before before the class `constructor` or the `connectedCallback` method is executed which are explained in the [overview](./ARCHITECTURE_OVERVIEW.md). This document explains specifically what `FASTElement` leverages inside the `HTMLElement`s lifecycle hooks.
+
+For an explanation into `HTMLElement` lifecycle hooks refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks).
+
+## A Custom Element is Detected by the Browser
+
+Because the `FASTElement` is an extension of the `HTMLElement`, it makes use of the same lifecycle hooks and extends them with `$fastController`. It also initializes using another class `ElementController`, the methods this are called during the custom elements native `constructor`, `connectedCallback`, `disconnectedCallback`, and `attributeChangedCallback` lifecycle hooks.
+
+### 🔄 **Lifecycle**: Initialization
+
+```mermaid
+flowchart TD
+    A[A <code>FASTElement</code> web component is added to the <code>DOM</code>] --> B
+    B[<code>FASTElement</code> initializes the <code>ElementController.forCustomElement</code> passing the Custom Element instance] --> C
+    B --> F[Observables applied to the <code>FASTElement</code> are updated on the FAST global without values]
+    C{Is an <code>ElementController</code> available?}
+    C --> |yes|E
+    C --> |no|D
+    D[Initialize a new <code>ElementController</code> referred to as setting an element controller strategy]
+    D --> F
+    E[<code>ElementController</code> captures the Custom Element instance and the definition and attaches them to the <code>$fastController</code> which is then attached to the instance]
+```
+
+### 🔄 **Lifecycle**: Component is connected
+
+```mermaid
+flowchart TD
+    A[browser <code>HTMLElement</code>'s <code>connectedCallback</code> is called] --> B
+    B[<code>this.$fastController.connect</code> in FASTElement is called] --> C
+    B --> D
+    B --> E
+    B --> F
+    C[bind observables by capturing the Custom Elements properties and setting the values from the bound observables on the Custom Element]
+    D[connect behaviors by call the <code>connectedCallback</code> on all behaviors]
+    E[render template, execute an <code>ElementViewTemplate</code>'s render method]
+    F[add styles either as an appended <code>StyleElement</code> node or an <code>adoptedStylesheet</code> which may include and attach behaviors]
+```
+
+#### Render Template
+
+The rendering of the template on the `ElementController` is by the `renderTemplate` method which is called during the `ElementController.connect` method which is triggered by `HTMLElement`s `connectedCallback` lifecycle.
+
+The `renderTemplate` identifies the Custom Element, and the shadow root associated with the Custom Element. This then places a rendering of the template (an `ElementView`) onto the internal `view` of the controller. When creating the `ElementView`/`HTMLView` using the `ViewTemplate.render`, the `Compile.compile()` method identifies a `DocumentFragment` either by using an existing `<template>` tag, or creating one to wrap the contents of the shadow root. A new `CompilationContext` is created and the `compileAttributes` function is called, this results in the replacement of the placeholder attributes initally set-up during the pre-render step with their values if a value has been assigned. The factories with the associated nodes identified are then passed to the context. The view then binds all behaviors to the source element. The `CompilationContext.createView` is executed with the `DocumentFragment` as the root, and returns an `HTMLView`. This `HTMLView` includes an `appendTo` method to attach the fragment to the host element, which it then does. It should be noted that the compiled HTML is a `string`, which when set on the `DocumentFragment` as `innerHTML`, this allows the browser to dictate the creation of HTML nodes.
+
+### 🔄 **Lifecycle**: Component is disconnected
+
+When a component is disconnected, a cleanup step is created to remove associated behaviors.
+
+### 🔄 **Lifecycle**: Attribute has been changed
+
+Attributes have an `AttributeDefinition` which allows for converters, attachment of the `<attributName>Changed` aspect of the `@attr` decorator among other capabilities.
+
+```mermaid
+flowchart TD
+    A[The browser <code>HTMLElement</code>'s <code>attributeChangedCallback</code> is called] --> B
+    B[<code>this.$fastController.onAttributeChangedCallback</code> in <code>FASTElement</code> is called] --> C
+    C[calls the attribute definitions <code>onAttributeChangedCallback</code> method with the updated value] --> D
+    D[An <code>Updates.enqueue</code> is called which places the update in the task queue which is then executed, these are performed async unless otherwise specified]
+```
+
+These changes are observed and similar to the way `Observables` work, they utilize an `Accessor` pattern which has a `getValue` and `setValue` in which DOM updates are applied.

package/ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md

@@ -0,0 +1,34 @@
+# `html` tagged template literal
+
+The `html` export from `@microsoft/fast-element` is used to create the template logic for the custom element.
+
+## Pre-processing the `html` tagged template literal contents
+
+Before the template can be used it goes through a step to convert it into a `ViewTemplate` which it does via the `ViewTemplate.create()` method. This is then used during the `compose` step, before `FASTElement` is instantiated.
+
+During the `Compiler.compile()` method(triggered by `ViewTemplate.create()` method), the following happens for each string:
+- Factories with unique IDs are created for each tag template literal argument (or `TemplateValue`) which matches with the corresponding string
+- A binding is created from the `TemplateValue`
+
+A resulting string using a `createHTML()` function is produced using the `HTMLDirective`s executed for each factory. The behavior is augmented by the previous string from the `html` tag template which determines the aspect if one exists, these aspects are the `@`, `:`, or other binding aspect attached to attributes.
+
+The `createHTML()` function utilizes a `Markup` attribute which is assigned to a factory's unique ID. The strings are concatenated and passed to a new `ViewTemplate` with all the factories (empty until one is assigned) that act as a dictionary with the unique IDs as the key to look up each factory once it has been created. The string this creates is injected into a `<template>` as `innerHTML`, which allows the browser to create the nodes and placeholder factory IDs, with the only `DOM` node that is explicitly created being the wrapping `<template>` element.
+
+## Directives
+
+The `HTMLBindingDirective` applies bindings to items identified as various `TemplateValue`s within the `html` tagged template. The `createHTML` step uses the factory associated with the binding to create strings in the markup using the factory's ID.
+
+```mermaid
+flowchart TD
+    A[A <code>new HTMLBindingDirective</code> is created with a data binding which has a policy, options, <code>createObserver</code>, and an evaluate method assigned to the passed arrow function such as <pre>x => x.foo</pre>]
+    B[<code>oneTime</code> binding passes the corresponding tag template argument, an arrow function]
+    C[<code>oneWay</code> binding passes a copy of the corresponding tag template argument, an arrow function]
+    D[An already specified binding such as a <code>repeat</code> or <code>when</code> directive is passed]
+    A --> B
+    A --> C
+    A --> D
+    E[When a <code>createObserver</code> is called, an <code>Observable.binding</code> is created passing the arrow function to be evaluated and the subscriber to be notified]
+    C --> E
+    F[When a <code>createObserver</code> is called, the instance of the one time binding is returned which includes a bind method returning the arrow function executed against the controller source and context]
+    B --> F
+```

package/ARCHITECTURE_INTRO.md

@@ -0,0 +1,10 @@
+# Introduction
+
+This document (and the linked documents) explains how the exports and side effects of `@microsoft/fast-element` are used to create custom elements.
+
+## Glossary
+
+- [Overview](./ARCHITECTURE_OVERVIEW.md): How the `@microsoft/fast-element` should be used by a developer and what code is executed during the first render.
+- [`FASTElement`](./ARCHITECTURE_FASTELEMENT.md): How the `FASTElement` is architected.
+- [`html` tagged template literal](./ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md): How the `html` tagged template literal takes and converts the contents into a `VIEWTemplate`.
+- [`Updates` queue](./ARCHITECTURE_UPDATES.md): How updates to attributes and observables are processed.

package/ARCHITECTURE_OVERVIEW.md

@@ -0,0 +1,52 @@
+# General FAST usage
+
+`FASTElement` is an extension of `HTMLElement` which makes use of Custom Element APIs native to the browser. It also supplies the following methods:
+
+- The `compose` method combines the Custom Element name, template, style, and other options to create the definition for the Custom Element.
+- The `define` method makes use of the native Custom Element [`define()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define) to register the Custom Element with a Custom Element Registry.
+- The `from` method allows the use of Customized Built-in elements, which extend from native elements such as `HTMLButtonElement`.
+
+### Creating a Custom Element from FASTElement
+
+A basic developer flow for defining a custom element looks like this:
+
+```mermaid
+flowchart TD
+    A[Create a <code>FASTElement</code> web component by extending the <code>FASTElement</code> class] --> F
+    F[Compose with <code>FASTElement.compose</code> to include template and styles] --> G[Define the component in the browser with <code>FASTElement.define</code>]
+```
+
+Let's take a look at the compose step to see what the FAST architecture is doing at this stage.
+
+### Composing a Custom Element
+
+The `FASTElement.compose()` function creates a new `FASTElementDefinition`, which includes all metadata needed for the element (such as templates, attributes, and styles). The element definition is registered with the global `FAST` for re-use, and the `FASTElementDefinition` is returned. The resulting object can be retrieved via `ElementController.definition`.
+
+## A Custom Element in JavaScript is sent to the Browser
+
+Let's step back from defining the Custom Element and consider what is happening when we import from the `@microsoft/fast-element` package.
+
+First, a global `FAST` property will be created if one does not already exist, typically in browser on the `window`.
+
+Additionally, when Custom Elements are included in a script a few things might happen even before a Custom Element gets detected by the browser. First, there are initial side effects caused by the use of decorators. These include the `attr` and `observable` decorators made available by the `@microsoft/fast-element` package.
+
+Here is a basic flow of what code is executed and when during initial load of a script that contains a FAST defined Custom Element:
+
+```mermaid
+flowchart TD
+    A@{ shape: circle, label: "The browser loads the JavaScript file containing FAST and FAST Custom Element definitions" }
+    B@{ shape: rect, label: "The FAST global is added to the window" }
+    A --> B
+    C@{ shape: rect, label: "A Custom Element executes the <code>compose</code> step"}
+    B --> C
+    D@{ shape: procs, label: "<ul style="text-align: left"><li>Any defined observable decorators are added to the FAST global</li><li>An attribute decorator locates the associated Custom Elements constructor which it uses to push itself to the Custom Elements attribute collection</li></ul>"}
+    C --> D
+    F@{ shape: rect, label: "An HTML tagged template literal is executed for the FAST Custom Element and applied to the definition" }
+    D --> F
+    G@{ shape: rect, label: "The <code>define</code> step is hit and the <code>customElement</code> is registered with the Custom Element Registry" }
+    F --> G
+    H@{ shape: rect, label: "A Custom Element is detected on the page and the browser initializes it" }
+    I@{ shape: dbl-circ, label: "The lifecycle steps for <code>FASTElement</code> are executed" }
+    G --> H
+    H --> I
+```

package/ARCHITECTURE_UPDATES.md

@@ -0,0 +1,11 @@
+# `Updates`
+
+The `Updates` API is part of the `FAST` global. The updates that are queued include updates to attributes, observables, and observed arrays.
+
+## Attributes
+
+An attribute change may be queued when the value of the attribute is updated. This change is triggered by `HTMLElement` lifecycle hook `attributeChangedCallback`. The `Updates` queue is used to try to reflect the attribute with the updated value onto the element using `DOM` APIs.
+
+## Observables
+
+The `Reflect` API is used to override `defineProperty` in order to observe a property on an Custom Element, this overrides the getter and setter, which allows subscribers to be notified of changes. Any changes which `set` the value are passed to the `Updates` queue.

package/CHANGELOG.json

@@ -1,6 +1,50 @@
 {
   "name": "@microsoft/fast-element",
   "entries": [
+    {
+      "date": "Thu, 13 Feb 2025 17:33:42 GMT",
+      "version": "2.1.0",
+      "tag": "@microsoft/fast-element_v2.1.0",
+      "comments": {
+        "minor": [
+          {
+            "author": "7559015+janechu@users.noreply.github.com",
+            "package": "@microsoft/fast-element",
+            "commit": "c4836e507f848b4838eb2c106c17dd18c28240b1",
+            "comment": "Update the ArrayObserver to better account for sort and reverse"
+          }
+        ],
+        "none": [
+          {
+            "author": "7559015+janechu@users.noreply.github.com",
+            "package": "@microsoft/fast-element",
+            "commit": "c6b9e8a436b7b52e5df02182b663167bb34cad8a",
+            "comment": "Add documentation explaining some architectural concepts"
+          }
+        ]
+      }
+    },
+    {
+      "date": "Wed, 11 Dec 2024 19:53:31 GMT",
+      "version": "2.0.1",
+      "tag": "@microsoft/fast-element_v2.0.1",
+      "comments": {
+        "patch": [
+          {
+            "author": "7559015+janechu@users.noreply.github.com",
+            "package": "@microsoft/fast-element",
+            "commit": "33111eeff26ab4ae2bbe1c90145170ed175d2217",
+            "comment": "Patch bumping to apply latest tag to the package"
+          },
+          {
+            "author": "abaris@null.net",
+            "package": "@microsoft/fast-element",
+            "commit": "51a79eb3294897fb1e71b5dcdcce0bea62521e80",
+            "comment": "fast-element: Simplify conditional checks in element-controller"
+          }
+        ]
+      }
+    },
     {
       "date": "Mon, 19 Aug 2024 22:04:19 GMT",
       "version": "2.0.0",

package/CHANGELOG.md

@@ -1,9 +1,26 @@
 # Change Log - @microsoft/fast-element
 
-This log was last generated on Mon, 19 Aug 2024 22:04:19 GMT and should not be manually modified.
+<!-- This log was last generated on Thu, 13 Feb 2025 17:33:42 GMT and should not be manually modified. -->
 
 <!-- Start content -->
 
+## 2.1.0
+
+Thu, 13 Feb 2025 17:33:42 GMT
+
+### Minor changes
+
+- Update the ArrayObserver to better account for sort and reverse (7559015+janechu@users.noreply.github.com)
+
+## 2.0.1
+
+Wed, 11 Dec 2024 19:53:31 GMT
+
+### Patches
+
+- Patch bumping to apply latest tag to the package (7559015+janechu@users.noreply.github.com)
+- fast-element: Simplify conditional checks in element-controller (abaris@null.net)
+
 ## 2.0.0
 
 Mon, 19 Aug 2024 22:04:19 GMT

package/dist/dts/components/attributes.d.ts

@@ -121,7 +121,7 @@ export declare class AttributeDefinition implements Accessor {
     /**
      * 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: HTMLElement, newValue: any): void;
     /**

package/dist/dts/index.d.ts

@@ -3,7 +3,7 @@ export { FAST, emptyArray } from "./platform.js";
 export { DOMAspect, DOMSink, DOMPolicy, DOM } from "./dom.js";
 export { Accessor, Expression, ExecutionContext, ExpressionController, ExpressionObserver, ExpressionNotifier, Observable, observable, ObservationRecord, SourceLifetime, volatile, } from "./observation/observable.js";
 export { Notifier, PropertyChangeNotifier, Subscriber, SubscriberSet, } from "./observation/notifier.js";
-export { ArrayObserver, LengthObserver, lengthOf, Splice, SpliceStrategy, SpliceStrategySupport, } from "./observation/arrays.js";
+export { ArrayObserver, LengthObserver, lengthOf, Splice, SpliceStrategy, SpliceStrategySupport, Sort, SortObserver, sortedCount, } from "./observation/arrays.js";
 export { UpdateQueue, Updates } from "./observation/update-queue.js";
 export { Binding, BindingDirective } from "./binding/binding.js";
 export { listener, oneWay } from "./binding/one-way.js";

package/dist/dts/observation/arrays.d.ts

@@ -33,6 +33,18 @@ export declare class Splice {
      */
     adjustTo(array: any[]): this;
 }
+/**
+ * A sort array indicates new index positions of array items.
+ * @public
+ */
+export declare class Sort {
+    sorted?: number[] | undefined;
+    /**
+     * Creates a sort update.
+     * @param sorted - The updated index of sorted items.
+     */
+    constructor(sorted?: number[] | undefined);
+}
 /**
  * Indicates what level of feature support the splice
  * strategy provides.
@@ -156,6 +168,17 @@ export interface LengthObserver extends Subscriber {
      */
     length: number;
 }
+/**
+ * Observes array sort.
+ * @public
+ */
+export interface SortObserver extends Subscriber {
+    /**
+     * The sorted times on the observed array, this should be incremented every time
+     * an item in the array changes location.
+     */
+    sorted: number;
+}
 /**
  * An observer for arrays.
  * @public
@@ -169,11 +192,20 @@ export interface ArrayObserver extends SubscriberSet {
      * The length observer for the array.
      */
     readonly lengthObserver: LengthObserver;
+    /**
+     * The sort observer for the array.
+     */
+    readonly sortObserver: SortObserver;
     /**
      * Adds a splice to the list of changes.
      * @param splice - The splice to add.
      */
     addSplice(splice: Splice): void;
+    /**
+     * Adds a sort to the list of changes.
+     * @param sort - The sort to add.
+     */
+    addSort(sort: Sort): void;
     /**
      * Indicates that a reset change has occurred.
      * @param oldCollection - The collection as it was before the reset.
@@ -189,6 +221,7 @@ export interface ArrayObserver extends SubscriberSet {
  * @public
  */
 export declare const ArrayObserver: Readonly<{
+    readonly sorted: 0;
     /**
      * Enables the array observation mechanism.
      * @remarks
@@ -205,3 +238,10 @@ export declare const ArrayObserver: Readonly<{
  * @public
  */
 export declare function lengthOf<T>(array: readonly T[]): number;
+/**
+ * Enables observing the sorted property of an array.
+ * @param array - The array to observe the sorted property of.
+ * @returns The sorted property.
+ * @public
+ */
+export declare function sortedCount<T>(array: readonly T[]): number;

package/dist/dts/templating/repeat.d.ts

@@ -1,4 +1,4 @@
-import { Splice } from "../observation/arrays.js";
+import { Sort, Splice } from "../observation/arrays.js";
 import type { Subscriber } from "../observation/notifier.js";
 import { Expression, ExpressionObserver } from "../observation/observable.js";
 import type { Binding, BindingDirective } from "../binding/binding.js";
@@ -81,9 +81,10 @@ export declare class RepeatBehavior<TSource = any> implements ViewBehavior, Subs
      * @param source - The source of the change.
      * @param args - The details about what was changed.
      */
-    handleChange(source: any, args: Splice[] | ExpressionObserver): void;
+    handleChange(source: any, args: Splice[] | Sort[] | ExpressionObserver): void;
     private observeItems;
-    private updateViews;
+    private updateSortedViews;
+    private updateSplicedViews;
     private refreshAllViews;
     private unbindAllViews;
     private hydrateViews;

package/dist/esm/components/attributes.js

@@ -26,13 +26,11 @@ export 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);
     },
 };
 /**
@@ -104,7 +102,7 @@ export 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];

package/dist/esm/debug.js

@@ -8,7 +8,7 @@ if (globalThis.FAST === void 0) {
 }
 const FAST = 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.",

package/dist/esm/index.js

@@ -4,7 +4,7 @@ export { DOMAspect, DOM } from "./dom.js";
 // Observation
 export { ExecutionContext, Observable, observable, SourceLifetime, volatile, } from "./observation/observable.js";
 export { PropertyChangeNotifier, SubscriberSet, } from "./observation/notifier.js";
-export { ArrayObserver, lengthOf, Splice, SpliceStrategy, SpliceStrategySupport, } from "./observation/arrays.js";
+export { ArrayObserver, lengthOf, Splice, SpliceStrategy, SpliceStrategySupport, Sort, sortedCount, } from "./observation/arrays.js";
 export { Updates } from "./observation/update-queue.js";
 // Binding
 export { Binding } from "./binding/binding.js";

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;