feat: add splice strategies for array observation (#5999)

* feat: extract splice merging to a strategy

* feat: enable splice strategy to control splice creation per array method

* feat: add reset splice strategy

* refactor: made array length observation part of the standard interface

* feat: add SpliceStrategySupport and fix enum/literals

* refactor: re-organize array observation code

* chore: add splice-strategies to the package and clean up exports

* Change files

* chore: remove invalid eslint comments

* test: add array observer tests for all array mutations

* fix: adding extensions back to exports

Co-authored-by: EisenbergEffect <[email protected]>

change/@microsoft-fast-element-19034156-dca2-4efc-8995-4003df6c2107.json

@@ -0,0 +1,7 @@
+{
+  "type": "major",
+  "comment": "feat: add splice strategies for array observation",
+  "packageName": "@microsoft/fast-element",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@microsoft-fast-foundation-0f273d05-e607-443b-ae31-aa5ab842432a.json

@@ -0,0 +1,7 @@
+{
+  "type": "major",
+  "comment": "chore: update imports to match latest fast-element exports",
+  "packageName": "@microsoft/fast-foundation",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/web-components/fast-element/docs/api-report.md

@@ -30,31 +30,43 @@ export class AdoptedStyleSheetsStrategy implements StyleStrategy {
     readonly sheets: CSSStyleSheet[];
 }
 
+// @public
+export interface ArrayObserver extends SubscriberSet {
+    addSplice(splice: Splice): void;
+    flush(): void;
+    readonly lengthObserver: LengthObserver;
+    reset(oldCollection: any[] | undefined): void;
+    strategy: SpliceStrategy | null;
+}
+
+// @public
+export const ArrayObserver: Readonly<{
+    readonly enable: () => void;
+}>;
+
 // @public
 export const Aspect: Readonly<{
-    none: 0;
-    attribute: 1;
-    booleanAttribute: 2;
-    property: 3;
-    content: 4;
-    tokenList: 5;
-    event: 6;
-    assign(directive: Aspected, value: string): void;
+    readonly none: 0;
+    readonly attribute: 1;
+    readonly booleanAttribute: 2;
+    readonly property: 3;
+    readonly content: 4;
+    readonly tokenList: 5;
+    readonly event: 6;
+    readonly assign: (directive: Aspected, value: string) => void;
 }>;
 
+// @public
+export type Aspect = typeof Aspect[Exclude<keyof typeof Aspect, "assign" | "none">];
+
 // @public
 export interface Aspected {
-    aspectType: AspectType;
+    aspectType: Aspect;
     binding?: Binding;
     sourceAspect: string;
     targetAspect: string;
 }
 
-// @public
-export type AspectType = Exclude<{
-    [K in keyof typeof Aspect]: typeof Aspect[K] extends number ? typeof Aspect[K] : never;
-}[keyof typeof Aspect], typeof Aspect.none>;
-
 // @public
 export function attr(config?: DecoratorAttributeConfiguration): (target: {}, property: string) => void;
 
@@ -118,7 +130,7 @@ export const BindingConfig: Readonly<{
 export type BindingConfigResolver<T> = (options: T) => BindingConfig<T>;
 
 // @public
-export type BindingMode = Record<AspectType, (directive: HTMLBindingDirective) => Pick<ViewBehaviorFactory, "createBehavior">>;
+export type BindingMode = Record<Aspect, (directive: HTMLBindingDirective) => Pick<ViewBehaviorFactory, "createBehavior">>;
 
 // @public
 export const BindingMode: Readonly<{
@@ -345,9 +357,6 @@ export interface ElementViewTemplate<TSource = any, TParent = any> {
 // @internal
 export const emptyArray: readonly never[];
 
-// @public
-export function enableArrayObservation(): void;
-
 // @public
 export class EventBinding {
     constructor(directive: HTMLBindingDirective);
@@ -430,7 +439,7 @@ export function html<TSource = any, TParent = any, TContext extends ExecutionCon
 // @public
 export class HTMLBindingDirective implements HTMLDirective, ViewBehaviorFactory, Aspected {
     constructor(binding: Binding, mode: BindingMode, options: any);
-    aspectType: AspectType;
+    aspectType: Aspect;
     // (undocumented)
     binding: Binding;
     createBehavior(targets: ViewBehaviorTargets): ViewBehavior;
@@ -512,6 +521,11 @@ export interface ItemViewTemplate<TSource = any, TParent = any> {
 function length_2<T>(array: readonly T[]): number;
 export { length_2 as length }
 
+// @public
+export interface LengthObserver extends Subscriber {
+    length: number;
+}
+
 // @public
 export const Markup: Readonly<{
     interpolation: (id: string) => string;
@@ -733,17 +747,46 @@ export interface SlottedDirectiveOptions<T = any> extends NodeBehaviorOptions<T>
 
 // @public
 export class Splice {
-    constructor(
-    index: number,
-    removed: any[],
-    addedCount: number);
+    constructor(index: number, removed: any[], addedCount: number);
+    // (undocumented)
     addedCount: number;
+    adjustTo(array: any[]): this;
+    // (undocumented)
     index: number;
     // (undocumented)
-    static normalize(previous: unknown[] | undefined, current: unknown[], changes: Splice[] | undefined): Splice[] | undefined;
     removed: any[];
+    reset?: boolean;
 }
 
+// @public
+export interface SpliceStrategy {
+    normalize(previous: unknown[] | undefined, current: unknown[], changes: Splice[] | undefined): readonly Splice[];
+    pop(array: any[], observer: ArrayObserver, pop: typeof Array.prototype.pop, args: any[]): any;
+    push(array: any[], observer: ArrayObserver, push: typeof Array.prototype.push, args: any[]): any;
+    reverse(array: any[], observer: ArrayObserver, reverse: typeof Array.prototype.reverse, args: any[]): any;
+    shift(array: any[], observer: ArrayObserver, shift: typeof Array.prototype.shift, args: any[]): any;
+    sort(array: any[], observer: ArrayObserver, sort: typeof Array.prototype.sort, args: any[]): any[];
+    splice(array: any[], observer: ArrayObserver, splice: typeof Array.prototype.splice, args: any[]): any;
+    readonly support: SpliceStrategySupport;
+    unshift(array: any[], observer: ArrayObserver, unshift: typeof Array.prototype.unshift, args: any[]): any[];
+}
+
+// @public
+export const SpliceStrategy: Readonly<{
+    readonly reset: Splice[];
+    readonly setDefaultStrategy: (strategy: SpliceStrategy) => void;
+}>;
+
+// @public
+export const SpliceStrategySupport: Readonly<{
+    readonly reset: 1;
+    readonly splice: 2;
+    readonly optimized: 3;
+}>;
+
+// @public
+export type SpliceStrategySupport = typeof SpliceStrategySupport[keyof typeof SpliceStrategySupport];
+
 // @public
 export abstract class StatelessAttachedAttributeDirective<T> implements HTMLDirective, ViewBehaviorFactory, ViewBehavior {
     constructor(options: T);

packages/web-components/fast-element/package.json

@@ -33,6 +33,10 @@
     "./debug.js": {
       "types": "./dist/dts/debug.d.ts",
       "default": "./dist/esm/debug.js"
+    },
+    "./splice-strategies.js": {
+      "types": "./dist/dts/observation/splice-strategies.d.ts",
+      "default": "./dist/esm/observation/splice-strategies.js"
     }
   },
   "unpkg": "dist/fast-element.min.js",

packages/web-components/fast-element/src/index.ts

@@ -14,8 +14,7 @@ export * from "./platform.js";
 // Observation
 export * from "./observation/observable.js";
 export * from "./observation/notifier.js";
-export * from "./observation/array-change-records.js";
-export * from "./observation/array-observer.js";
+export * from "./observation/arrays.js";
 export * from "./observation/update-queue.js";
 export type { Behavior } from "./observation/behavior.js";