fix: address PR review feedback

- enableHydration() now calls ensureDeclarativeRuntime() so html
  templates become hydratable (#1)
- TemplateElement.config() enables hydration when per-element
  callbacks (elementWillHydrate/elementDidHydrate) are configured (#2)
- ElementStyles lazily initializes DefaultStyleStrategy so styles.js
  subpath works standalone without element-controller (#3)
- Disable dtsRollup in all subpath api-extractor configs (#4)
- Re-export moved types (ElementStyles, HostBehavior, etc.) as type
  exports from root barrel (#5)
- Add api-extractor configs for styles.js and arrays.js subpaths (#6)
- Update 3.x docs to import css from styles.js subpath (#7)
- Fix migration guide New Exports table with current APIs (#8)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: janechu

packages/fast-element/SIZES.md

@@ -4,8 +4,8 @@ Bundle sizes for `@microsoft/fast-element` exports.
 
 | Export | Minified | Gzip | Brotli |
 |--------|----------|------|--------|
-| CDN Rollup Bundle | 63.66 KB | 19.00 KB | 17.01 KB |
-| FASTElement | 22.83 KB | 7.19 KB | 6.49 KB |
+| CDN Rollup Bundle | 65.17 KB | 19.44 KB | 17.34 KB |
+| FASTElement | 23.71 KB | 7.37 KB | 6.63 KB |
 | Updates | 473 B | 337 B | 287 B |
 | Observable | 6.70 KB | 2.49 KB | 2.22 KB |
 | observable | 6.74 KB | 2.50 KB | 2.24 KB |
@@ -17,7 +17,7 @@ Bundle sizes for `@microsoft/fast-element` exports.
 | when | 1.82 KB | 712 B | 568 B |
 | html | 25.92 KB | 8.50 KB | 7.61 KB |
 | repeat | 29.57 KB | 9.42 KB | 8.47 KB |
-| css | 1.55 KB | 731 B | 654 B |
-| ElementStyles | 788 B | 397 B | 332 B |
-| enableHydration | 24.27 KB | 7.59 KB | 6.86 KB |
+| css | 2.43 KB | 1.00 KB | 911 B |
+| ElementStyles | 1.65 KB | 729 B | 623 B |
+| enableHydration | 43.33 KB | 13.30 KB | 11.93 KB |
 | ArrayObserver | 12.51 KB | 4.45 KB | 4.01 KB |

packages/fast-element/api-extractor.arrays.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+    "extends": "../../api-extractor.json",
+    "mainEntryPointFilePath": "./dist/dts/arrays.d.ts",
+    "dtsRollup": { "enabled": false },
+    "apiReport": {
+        "enabled": true,
+        "reportFolder": "<projectFolder>/docs/arrays",
+        "reportFileName": "api-report"
+    },
+    "docModel": {
+        "enabled": true,
+        "apiJsonFilePath": "<projectFolder>/dist/arrays/arrays.api.json"
+    }
+}

packages/fast-element/api-extractor.context.json

@@ -2,6 +2,7 @@
     "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
     "extends": "../../api-extractor.json",
     "mainEntryPointFilePath": "./dist/dts/context.d.ts",
+    "dtsRollup": { "enabled": false },
     "apiReport": {
         "enabled": true,
         "reportFolder": "<projectFolder>/docs/context",

packages/fast-element/api-extractor.declarative.json

@@ -2,6 +2,7 @@
     "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
     "extends": "../../api-extractor.json",
     "mainEntryPointFilePath": "./dist/dts/declarative.d.ts",
+    "dtsRollup": { "enabled": false },
     "apiReport": {
         "enabled": true,
         "reportFolder": "<projectFolder>/docs/declarative",

packages/fast-element/api-extractor.di.json

@@ -2,6 +2,7 @@
     "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
     "extends": "../../api-extractor.json",
     "mainEntryPointFilePath": "./dist/dts/di/di.d.ts",
+    "dtsRollup": { "enabled": false },
     "apiReport": {
         "enabled": true,
         "reportFolder": "<projectFolder>/docs/di",

packages/fast-element/api-extractor.hydration.json

@@ -2,6 +2,7 @@
     "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
     "extends": "../../api-extractor.json",
     "mainEntryPointFilePath": "./dist/dts/hydration.d.ts",
+    "dtsRollup": { "enabled": false },
     "apiReport": {
         "enabled": true,
         "reportFolder": "<projectFolder>/docs/hydration",

packages/fast-element/api-extractor.styles.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+    "extends": "../../api-extractor.json",
+    "mainEntryPointFilePath": "./dist/dts/styles.d.ts",
+    "dtsRollup": { "enabled": false },
+    "apiReport": {
+        "enabled": true,
+        "reportFolder": "<projectFolder>/docs/styles",
+        "reportFileName": "api-report"
+    },
+    "docModel": {
+        "enabled": true,
+        "apiJsonFilePath": "<projectFolder>/dist/styles/styles.api.json"
+    }
+}

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

@@ -134,6 +134,9 @@ export const Compiler: {
     aggregate(parts: (string | ViewBehaviorFactory)[], policy?: DOMPolicy): ViewBehaviorFactory;
 };
 
+// @public
+export type ComposableStyles = string | ElementStyles | CSSStyleSheet;
+
 // @public
 export type Constructable<T = {}> = {
     new (...args: any[]): T;
@@ -196,15 +199,12 @@ export interface DOMPolicy {
 // @public
 export type DOMSink = (target: Node, aspectName: string, value: any, ...args: any[]) => void;
 
-// Warning: (ae-forgotten-export) The symbol "HostController" needs to be exported by the entry point index.d.ts
-//
 // @public
 export class ElementController<TElement extends HTMLElement = HTMLElement> implements Notifier, HostController<TElement> {
     // @internal
     constructor(element: TElement, definition: FASTElementDefinition);
     addBehavior(behavior: HostBehavior<TElement>): void;
     addStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
-    // Warning: (ae-forgotten-export) The symbol "HostBehavior" needs to be exported by the entry point index.d.ts
     protected behaviors: Map<HostBehavior<TElement>, number> | null;
     protected bindObservables(): void;
     protected captureBoundObservables(): void;
@@ -223,7 +223,6 @@ export class ElementController<TElement extends HTMLElement = HTMLElement> imple
     get isConnected(): boolean;
     readonly isHydrated: Promise<boolean>;
     readonly isPrerendered: Promise<boolean>;
-    // Warning: (ae-forgotten-export) The symbol "ElementStyles" needs to be exported by the entry point index.d.ts
     get mainStyles(): ElementStyles | null;
     set mainStyles(value: ElementStyles | null);
     protected needsInitialization: boolean;
@@ -263,6 +262,25 @@ export const elements: (selector?: string) => ElementsFilter;
 // @public
 export type ElementsFilter = (value: Node, index?: number, array?: Node[]) => boolean;
 
+// @public
+export class ElementStyles {
+    constructor(styles: ReadonlyArray<ComposableStyles>);
+    // @internal (undocumented)
+    addStylesTo(target: StyleTarget): void;
+    // @internal (undocumented)
+    isAttachedTo(target: StyleTarget): boolean;
+    static normalize(styles: ComposableStyles | ComposableStyles[] | undefined): ElementStyles | undefined;
+    // @internal (undocumented)
+    removeStylesFrom(target: StyleTarget): void;
+    static setDefaultStrategy(Strategy: ConstructibleStyleStrategy): void;
+    get strategy(): StyleStrategy;
+    // (undocumented)
+    readonly styles: ReadonlyArray<ComposableStyles>;
+    static readonly supportsAdoptedStyleSheets: boolean;
+    // Warning: (ae-forgotten-export) The symbol "ConstructibleStyleStrategy" needs to be exported by the entry point index.d.ts
+    withStrategy(Strategy: ConstructibleStyleStrategy): this;
+}
+
 // @public
 export interface ElementView<TSource = any, TParent = any> extends View<TSource, TParent> {
     appendTo(node: Node): void;
@@ -393,6 +411,24 @@ export const fastElementRegistry: TypeRegistry<FASTElementDefinition>;
 // @public
 export type FASTElementTemplateResolver<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>> = (definition: FASTElementDefinition<TType>) => ElementViewTemplate<InstanceType<TType>> | Promise<ElementViewTemplate<InstanceType<TType>>>;
 
+// @public
+export interface HostBehavior<TSource = any> {
+    addedCallback?(controller: HostController<TSource>): void;
+    connectedCallback?(controller: HostController<TSource>): void;
+    disconnectedCallback?(controller: HostController<TSource>): void;
+    removedCallback?(controller: HostController<TSource>): void;
+}
+
+// @public
+export interface HostController<TSource = any> extends ExpressionController<TSource> {
+    addBehavior(behavior: HostBehavior<TSource>): void;
+    addStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
+    readonly isConnected: boolean;
+    mainStyles: ElementStyles | null;
+    removeBehavior(behavior: HostBehavior<TSource>, force?: boolean): void;
+    removeStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
+}
+
 // @public
 export const html: HTMLTemplateTag;
 
@@ -638,7 +674,6 @@ export interface PartialFASTElementDefinition<TType extends Constructable<HTMLEl
     readonly name: string;
     readonly registry?: CustomElementRegistry;
     readonly shadowOptions?: Partial<ShadowRootOptions> | null;
-    // Warning: (ae-forgotten-export) The symbol "ComposableStyles" needs to be exported by the entry point index.d.ts
     readonly styles?: ComposableStyles | ComposableStyles[];
     readonly template?: ElementViewTemplate<InstanceType<TType>> | FASTElementTemplateResolver<TType>;
 }
@@ -699,8 +734,6 @@ export function repeat<TSource = any, TArray extends ReadonlyArray<any> = Readon
 export class RepeatBehavior<TSource = any> implements ViewBehavior, Subscriber {
     constructor(directive: RepeatDirective);
     bind(controller: ViewController): void;
-    // Warning: (ae-forgotten-export) The symbol "Splice" needs to be exported by the entry point index.d.ts
-    // Warning: (ae-forgotten-export) The symbol "Sort" needs to be exported by the entry point index.d.ts
     handleChange(source: any, args: Splice[] | Sort[] | ExpressionObserver): void;
     unbind(): void;
     // @internal (undocumented)
@@ -749,6 +782,13 @@ export class SlottedDirective extends NodeObservationDirective<SlottedDirectiveO
 export interface SlottedDirectiveOptions<T = any> extends NodeBehaviorOptions<T>, AssignedNodesOptions {
 }
 
+// @public
+export class Sort {
+    constructor(sorted?: number[] | undefined);
+    // (undocumented)
+    sorted?: number[] | undefined;
+}
+
 // @public
 export const SourceLifetime: Readonly<{
     readonly unknown: undefined;
@@ -758,6 +798,19 @@ export const SourceLifetime: Readonly<{
 // @public
 export type SourceLifetime = (typeof SourceLifetime)[keyof typeof SourceLifetime];
 
+// @public
+export class Splice {
+    constructor(index: number, removed: any[], addedCount: number);
+    // (undocumented)
+    addedCount: number;
+    adjustTo(array: any[]): this;
+    // (undocumented)
+    index: number;
+    // (undocumented)
+    removed: any[];
+    reset?: boolean;
+}
+
 // @public
 export const enum Stages {
     connected = 1,
@@ -776,6 +829,20 @@ export abstract class StatelessAttachedAttributeDirective<TOptions> implements H
     protected options: TOptions;
 }
 
+// @public
+export interface StyleStrategy {
+    addStylesTo(target: StyleTarget): void;
+    removeStylesFrom(target: StyleTarget): void;
+}
+
+// @public
+export interface StyleTarget extends Pick<Node, "getRootNode"> {
+    adoptedStyleSheets?: CSSStyleSheet[];
+    append(styles: HTMLStyleElement): void;
+    querySelectorAll<E extends Element = Element>(selectors: string): NodeListOf<E>;
+    removeChild(styles: HTMLStyleElement): void;
+}
+
 // @public
 export interface Subscriber {
     handleChange(subject: any, args: any): void;

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

@@ -0,0 +1,95 @@
+## API Report File for "@microsoft/fast-element"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+// Warning: (ae-forgotten-export) The symbol "SubscriberSet" needs to be exported by the entry point arrays.d.ts
+//
+// @public
+export interface ArrayObserver extends SubscriberSet {
+    addSort(sort: Sort): void;
+    addSplice(splice: Splice): void;
+    flush(): void;
+    readonly lengthObserver: LengthObserver;
+    reset(oldCollection: any[] | undefined): void;
+    readonly sortObserver: SortObserver;
+    strategy: SpliceStrategy | null;
+}
+
+// @public
+export const ArrayObserver: Readonly<{
+    readonly sorted: 0;
+    readonly enable: () => void;
+}>;
+
+// Warning: (ae-forgotten-export) The symbol "Subscriber" needs to be exported by the entry point arrays.d.ts
+//
+// @public
+export interface LengthObserver extends Subscriber {
+    length: number;
+}
+
+// @public
+export function lengthOf<T>(array: readonly T[]): number;
+
+// @public
+export class Sort {
+    constructor(sorted?: number[] | undefined);
+    // (undocumented)
+    sorted?: number[] | undefined;
+}
+
+// @public
+export function sortedCount<T>(array: readonly T[]): number;
+
+// @public
+export interface SortObserver extends Subscriber {
+    sorted: number;
+}
+
+// @public
+export class Splice {
+    constructor(index: number, removed: any[], addedCount: number);
+    // (undocumented)
+    addedCount: number;
+    adjustTo(array: any[]): this;
+    // (undocumented)
+    index: number;
+    // (undocumented)
+    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];
+
+// (No @packageDocumentation comment for this package)
+
+```