feat: add extensions array argument to FASTElement.define() (#7465)

# Pull Request

## 📖 Description

Adds support for an optional extensions array parameter on `FASTElement.define()` and `FASTElementDefinition.define()`. Extensions are `FASTElementExtension` callbacks that receive the resolved `FASTElementDefinition` and are invoked **before** platform registration via `customElements.define()`, enabling a plugin pattern for element registration hooks.

**Example:**
```typescript
class MyComponent extends FASTElement {}

MyComponent.define({
    name: "my-component"
}, [myPlugin()]);
```

## 👩‍💻 Reviewer Notes

- Extensions run before `customElements.define()` so side-effects are available before element upgrade.
- The `FASTElementExtension` type receives the full `FASTElementDefinition` (not `PartialFASTElementDefinition`) so extensions have access to resolved metadata.
- Both method-style (`MyEl.define(config, extensions)`) and static-style (`FASTElement.define(MyEl, config, extensions)`) calling conventions are supported.
- Rebased onto latest `releases/fast-element-v3` which made `compose`/`define` async (returning Promises). The extensions parameter integrates with the new async `define` flow — extensions are passed through to `FASTElementDefinition.define()` and invoked before platform registration.
- Removed the separate `composeAsync`/`defineAsync` methods that were previously in this branch since the base branch now handles async natively.

## 📑 Test Plan

All existing fast-element tests pass. Added 7 new Playwright tests covering:
- Method-style define with extensions
- Static-style define with extensions
- Multiple extensions called in order
- Extensions called before platform registration
- Empty extensions array
- Extension receives FASTElementDefinition instance
- Factory pattern with extensions

## ✅ Checklist

### General

- [x] I have included a change request file using `$ npm run change`
- [x] I have added tests for my changes.
- [x] I have tested my changes.
- [x] I have updated the project documentation to reflect my changes.
- [x] I have read the [CONTRIBUTING](https://github.com/microsoft/fast/blob/main/CONTRIBUTING.md) documentation and followed the [standards](https://github.com/microsoft/fast/blob/main/CODE_OF_CONDUCT.md#our-standards) for this project.

Author: janechu

change/@microsoft-fast-element-748c99d5-48b4-4910-bb6c-e62520907383.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Add extensions array argument to FASTElement.define() and FASTElementDefinition.define()",
+  "packageName": "@microsoft/fast-element",
+  "email": "7559015+janechu@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}

packages/fast-element/DESIGN.md

@@ -103,6 +103,26 @@ The `KernelServiceId` object controls which numeric/string keys are used for sha
 
 `FASTElementDefinition` wraps all the metadata for a custom element class: its tag name, template, styles, and observed attribute list. It is created by `FASTElement.compose()` (which returns `Promise<FASTElementDefinition>`, always resolving immediately) and registered globally via `fastElementRegistry`. `FASTElement.define()` returns `Promise<TType>` — resolving immediately for complete definitions or deferring when `templateOptions` is `"defer-and-hydrate"` and no template is provided. `FASTElementDefinition.register()` returns `Promise<Function>` — resolving when a definition with the given name has been registered.
 
+#### Extensions
+
+`FASTElement.define()` and `FASTElementDefinition.define()` accept an optional array of **extension callbacks** (`FASTElementExtension`). Each extension is a function that receives the resolved `FASTElementDefinition` and is invoked **before** the element is registered with the platform via `customElements.define()`. This allows plugins to inspect or act on the definition metadata (name, template, styles, attributes) before any existing DOM elements are upgraded.
+
+```typescript
+type FASTElementExtension = (definition: FASTElementDefinition) => void;
+```
+
+Extensions are typically produced by factory functions:
+
+```typescript
+function myPlugin() {
+    return (definition: FASTElementDefinition) => {
+        console.log(`Registering: ${definition.name}`);
+    };
+}
+
+MyComponent.define({ name: "my-component" }, [myPlugin()]);
+```
+
 ---
 
 ### Observables & Notifiers

packages/fast-element/README.md

@@ -72,4 +72,31 @@ this.$fastController.isPrerendered.then(prerendered => {
 });
 ```
 
-Custom directives can also await `controller.isPrerendered` (a `Promise<boolean>` on the `ViewController` interface) to determine whether the view's content was prerendered.
+Custom directives can also await `controller.isPrerendered` (a `Promise<boolean>` on the `ViewController` interface) to determine whether the view's content was prerendered.
+
+## Define Extensions
+
+`FASTElement.define()` accepts an optional second argument — an array of extension callbacks that are invoked with the resolved element definition before the element is registered with the platform. This enables a plugin pattern where reusable behaviors can hook into element registration.
+
+```typescript
+import { FASTElement } from "@microsoft/fast-element";
+import type { FASTElementExtension } from "@microsoft/fast-element";
+
+function logger(): FASTElementExtension {
+    return definition => {
+        console.log(`Defining element: ${definition.name}`);
+    };
+}
+
+class MyComponent extends FASTElement {
+    // component code
+}
+
+// Method style
+MyComponent.define({ name: "my-component", template, styles }, [logger()]);
+
+// Static style
+FASTElement.define(MyComponent, { name: "my-component" }, [logger()]);
+```
+
+Each extension receives the full `FASTElementDefinition`, which includes the resolved element name, type, template, styles, and attribute metadata. Extensions run before `customElements.define()`, so any setup they perform is available when existing DOM elements are upgraded.

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

@@ -453,7 +453,7 @@ export class FASTElementDefinition<TType extends Constructable<HTMLElement> = Co
     readonly attributeLookup: Record<string, AttributeDefinition>;
     readonly attributes: ReadonlyArray<AttributeDefinition>;
     static compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): Promise<FASTElementDefinition<TType>>;
-    define(registry?: CustomElementRegistry): this;
+    define(registry?: CustomElementRegistry, extensions?: FASTElementExtension[]): this;
     readonly elementOptions: ElementDefinitionOptions;
     static readonly getByType: (key: Function) => FASTElementDefinition<Constructable<HTMLElement>> | undefined;
     static readonly getForInstance: (object: any) => FASTElementDefinition<Constructable<HTMLElement>> | undefined;
@@ -475,6 +475,9 @@ export class FASTElementDefinition<TType extends Constructable<HTMLElement> = Co
     readonly type: TType;
 }
 
+// @public
+export type FASTElementExtension = (definition: FASTElementDefinition) => void;
+
 // Warning: (ae-internal-missing-underscore) The name "fastElementRegistry" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal

packages/fast-element/src/components/fast-definitions.ts

@@ -63,6 +63,14 @@ export interface TemplateLifecycleCallbacks {
     elementDidDefine?(name: string): void;
 }
 
+/**
+ * A callback that receives a FASTElementDefinition during element registration.
+ * Extensions are invoked before the element is registered with the platform,
+ * allowing plugins to inspect or act on the resolved definition.
+ * @public
+ */
+export type FASTElementExtension = (definition: FASTElementDefinition) => void;
+
 /**
  * Represents metadata configuration for a custom element.
  * @public
@@ -261,13 +269,24 @@ export class FASTElementDefinition<
     /**
      * Defines a custom element based on this definition.
      * @param registry - The element registry to define the element in.
+     * @param extensions - An optional array of extension callbacks to invoke
+     * with this definition before platform registration.
      * @remarks
      * This operation is idempotent per registry.
      */
-    public define(registry: CustomElementRegistry = this.registry): this {
+    public define(
+        registry: CustomElementRegistry = this.registry,
+        extensions?: FASTElementExtension[],
+    ): this {
         const type = this.type;
 
         if (!registry.get(this.name)) {
+            if (extensions) {
+                for (const extension of extensions) {
+                    extension(this);
+                }
+            }
+
             this.platformDefined = true;
             registry.define(this.name, type as any, this.elementOptions);
             this.lifecycleCallbacks?.elementDidDefine?.(this.name);
@@ -334,6 +353,7 @@ export class FASTElementDefinition<
             );
         });
     };
+ 
 }
 
 Observable.defineProperty(FASTElementDefinition.prototype, "template");

packages/fast-element/src/components/fast-element.pw.spec.ts

@@ -25,4 +25,200 @@ test.describe("FASTElement", () => {
 
         expect(hasProperties).toBe(true);
     });
+
+    test.describe("define with extensions", () => {
+        test("should call extensions with the definition when using method style", async ({
+            page,
+        }) => {
+            await page.goto("/");
+
+            const result = await page.evaluate(async () => {
+                // @ts-expect-error: Client module.
+                const { FASTElement, uniqueElementName } = await import("/main.js");
+
+                const extensionCalls: string[] = [];
+
+                class TestElement extends FASTElement {}
+
+                const elName = uniqueElementName();
+                const extension = (def: any) => {
+                    extensionCalls.push(def.name);
+                };
+
+                await TestElement.define({ name: elName }, [extension]);
+
+                return {
+                    callCount: extensionCalls.length,
+                    receivedName: extensionCalls[0],
+                    expectedName: elName,
+                };
+            });
+
+            expect(result.callCount).toBe(1);
+            expect(result.receivedName).toBe(result.expectedName);
+        });
+
+        test("should call extensions with the definition when using static style", async ({
+            page,
+        }) => {
+            await page.goto("/");
+
+            const result = await page.evaluate(async () => {
+                // @ts-expect-error: Client module.
+                const { FASTElement, uniqueElementName } = await import("/main.js");
+
+                const extensionCalls: string[] = [];
+
+                class TestElement extends FASTElement {}
+
+                const elName = uniqueElementName();
+                const extension = (def: any) => {
+                    extensionCalls.push(def.name);
+                };
+
+                await FASTElement.define(TestElement, { name: elName }, [extension]);
+
+                return {
+                    callCount: extensionCalls.length,
+                    receivedName: extensionCalls[0],
+                    expectedName: elName,
+                };
+            });
+
+            expect(result.callCount).toBe(1);
+            expect(result.receivedName).toBe(result.expectedName);
+        });
+
+        test("should call multiple extensions in order", async ({ page }) => {
+            await page.goto("/");
+
+            const result = await page.evaluate(async () => {
+                // @ts-expect-error: Client module.
+                const { FASTElement, uniqueElementName } = await import("/main.js");
+
+                const calls: number[] = [];
+
+                class TestElement extends FASTElement {}
+
+                await TestElement.define({ name: uniqueElementName() }, [
+                    () => calls.push(1),
+                    () => calls.push(2),
+                    () => calls.push(3),
+                ]);
+
+                return calls;
+            });
+
+            expect(result).toEqual([1, 2, 3]);
+        });
+
+        test("should call extensions before platform registration", async ({ page }) => {
+            await page.goto("/");
+
+            const result = await page.evaluate(async () => {
+                // @ts-expect-error: Client module.
+                const { FASTElement, uniqueElementName } = await import("/main.js");
+
+                let wasDefinedDuringExtension = false;
+
+                class TestElement extends FASTElement {}
+
+                const elName = uniqueElementName();
+
+                await TestElement.define({ name: elName }, [
+                    () => {
+                        wasDefinedDuringExtension =
+                            customElements.get(elName) !== undefined;
+                    },
+                ]);
+
+                const isDefinedAfter = customElements.get(elName) !== undefined;
+
+                return { wasDefinedDuringExtension, isDefinedAfter };
+            });
+
+            expect(result.wasDefinedDuringExtension).toBe(false);
+            expect(result.isDefinedAfter).toBe(true);
+        });
+
+        test("should work with an empty extensions array", async ({ page }) => {
+            await page.goto("/");
+
+            const isDefined = await page.evaluate(async () => {
+                // @ts-expect-error: Client module.
+                const { FASTElement, uniqueElementName } = await import("/main.js");
+
+                class TestElement extends FASTElement {}
+
+                const elName = uniqueElementName();
+                await TestElement.define({ name: elName }, []);
+
+                return customElements.get(elName) !== undefined;
+            });
+
+            expect(isDefined).toBe(true);
+        });
+
+        test("should pass a FASTElementDefinition to the extension", async ({ page }) => {
+            await page.goto("/");
+
+            const result = await page.evaluate(async () => {
+                // @ts-expect-error: Client module.
+                const { FASTElement, FASTElementDefinition, uniqueElementName } =
+                    await import("/main.js");
+
+                let receivedDef: any = null;
+
+                class TestElement extends FASTElement {}
+
+                const elName = uniqueElementName();
+                await TestElement.define({ name: elName }, [
+                    def => {
+                        receivedDef = def;
+                    },
+                ]);
+
+                return {
+                    isDefinitionInstance: receivedDef instanceof FASTElementDefinition,
+                    hasName: receivedDef?.name === elName,
+                    hasType: typeof receivedDef?.type === "function",
+                };
+            });
+
+            expect(result.isDefinitionInstance).toBe(true);
+            expect(result.hasName).toBe(true);
+            expect(result.hasType).toBe(true);
+        });
+
+        test("factory pattern should work with extensions", async ({ page }) => {
+            await page.goto("/");
+
+            const result = await page.evaluate(async () => {
+                // @ts-expect-error: Client module.
+                const { FASTElement, uniqueElementName } = await import("/main.js");
+
+                const calls: string[] = [];
+
+                function myPlugin() {
+                    return (def: any) => {
+                        calls.push(`plugin:${def.name}`);
+                    };
+                }
+
+                class TestElement extends FASTElement {}
+
+                const elName = uniqueElementName();
+                await TestElement.define({ name: elName }, [myPlugin()]);
+
+                return {
+                    callCount: calls.length,
+                    firstCall: calls[0],
+                    expectedCall: `plugin:${elName}`,
+                };
+            });
+
+            expect(result.callCount).toBe(1);
+            expect(result.firstCall).toBe(result.expectedCall);
+        });
+    });
 });

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

@@ -3,6 +3,7 @@ import { Observable } from "../observation/observable.js";
 import { ElementController } from "./element-controller.js";
 import {
     FASTElementDefinition,
+    type FASTElementExtension,
     type PartialFASTElementDefinition,
     TemplateOptions,
 } from "./fast-definitions.js";
@@ -129,17 +130,28 @@ function compose<TType extends Constructable<HTMLElement> = Constructable<HTMLEl
 function define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(
     this: TType,
     nameOrDef: string | PartialFASTElementDefinition,
+    extensions?: FASTElementExtension[],
 ): Promise<TType>;
 function define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(
     type: TType,
     nameOrDef?: string | PartialFASTElementDefinition,
+    extensions?: FASTElementExtension[],
 ): Promise<TType>;
 function define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(
     type: TType | string | PartialFASTElementDefinition,
-    nameOrDef?: string | PartialFASTElementDefinition,
+    nameOrDef?: string | PartialFASTElementDefinition | FASTElementExtension[],
+    extensions?: FASTElementExtension[],
 ): Promise<TType> {
+    if (Array.isArray(nameOrDef)) {
+        extensions = nameOrDef;
+        nameOrDef = undefined;
+    }
+
     const composePromise = isFunction(type)
-        ? FASTElementDefinition.compose(type, nameOrDef)
+        ? FASTElementDefinition.compose(
+              type,
+              nameOrDef as string | PartialFASTElementDefinition | undefined,
+          )
         : FASTElementDefinition.compose(this, type);
 
     return composePromise.then(def => {
@@ -150,14 +162,14 @@ function define<TType extends Constructable<HTMLElement> = Constructable<HTMLEle
                     handleChange: () => {
                         notifier.unsubscribe(subscriber, "template");
                         def.lifecycleCallbacks?.templateDidUpdate?.(def.name);
-                        resolve(def.define().type);
+                        resolve(def.define(undefined, extensions).type);
                     },
                 };
                 notifier.subscribe(subscriber, "template");
             });
         }
 
-        return def.define().type;
+        return def.define(undefined, extensions).type;
     });
 }