refactor: move observerMap/attributeMap to fast-element as FASTElementExtension factories

- Create packages/fast-element/src/extensions/observer-map.ts and attribute-map.ts
  as FASTElementExtension factory functions with ObserverMap/AttributeMap classes
- Create packages/fast-element/src/extensions/schema.ts with Schema class and types
- Create packages/fast-element/src/extensions/utilities.ts with observable proxy
  utilities (assignObservables, deepMerge, assignProxy, deepEqual, etc.)
- Add sub-path exports for extensions in fast-element package.json
- Add extensions parameter to FASTElementDefinition.compose() for synchronous
  execution after definition construction (critical for timing with TemplateElement)
- Update FASTElement.define() to accept and forward extensions array
- Remove ObserverMap, AttributeMap classes and proxy utilities from fast-html
- Replace fast-html schema.ts with re-exports from fast-element
- Update all fixture files to import deepMerge from fast-element
- Update DESIGN.md, README.md, SCHEMA_OBSERVER_MAP.md, WRITING_FIXTURES.md
- Regenerate API reports and website API docs
- Add beachball change files for both packages

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

Author: janechu

…-convert-observer-map-attribute-map.json …9d26cf5-d4e3-43ad-ae88-056745023268.jsonchange/@microsoft-fast-element-convert-observer-map-attribute-map.json renamed to change/@microsoft-fast-element-b9d26cf5-d4e3-43ad-ae88-056745023268.json change/@microsoft-fast-element-convert-observer-map-attribute-map.json renamed to change/@microsoft-fast-element-b9d26cf5-d4e3-43ad-ae88-056745023268.json

@@ -1,6 +1,6 @@
 {
   "type": "minor",
-  "comment": "Add observerMap() and attributeMap() FASTElementExtension factories; add extensions parameter to FASTElementDefinition.compose()",
+  "comment": "refactor: move observerMap/attributeMap to fast-element as FASTElementExtension factories",
   "packageName": "@microsoft/fast-element",
   "email": "7559015+janechu@users.noreply.github.com",
   "dependentChangeType": "none"

change/@microsoft-fast-html-94dc05b9-99f5-4387-bd18-25a250604554.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "refactor: move observerMap/attributeMap to fast-element as FASTElementExtension factories",
+  "packageName": "@microsoft/fast-html",
+  "email": "7559015+janechu@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

change/@microsoft-fast-html-convert-observer-map-attribute-map.json

@@ -4,6 +4,16 @@
 
 ```ts
 
+// Warning: (ae-forgotten-export) The symbol "CachedPathCommon" needs to be exported by the entry point index.d.ts
+//
+// @public (undocumented)
+export interface AccessCachedPath extends CachedPathCommon {
+    // Warning: (ae-forgotten-export) The symbol "AccessCachedPathType" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    type: AccessCachedPathType;
+}
+
 // @public
 export interface Accessor {
     getValue(source: any): any;
@@ -42,6 +52,12 @@ export interface Aspected {
     targetAspect: string;
 }
 
+// @public
+export function assignObservables(schema: JSONSchema | JSONSchemaDefinition, rootSchema: JSONSchema, data: any, target: any, rootProperty: string): typeof Proxy;
+
+// @public
+export function assignProxy(schema: JSONSchema | JSONSchemaDefinition, rootSchema: JSONSchema, target: any, rootProperty: string, object: any): typeof Proxy;
+
 // @public
 export function attr(config?: DecoratorAttributeConfiguration): (target: {}, property: string) => void;
 
@@ -77,6 +93,13 @@ export class AttributeDefinition implements Accessor {
     setValue(source: HTMLElement, newValue: any): void;
 }
 
+// @public
+export class AttributeMap {
+    constructor(classPrototype: any, schema: Schema, definition?: FASTElementDefinition, config?: AttributeMapConfig);
+    // (undocumented)
+    defineProperties(): void;
+}
+
 // @public
 export function attributeMap(config?: AttributeMapConfig): FASTElementExtension;
 
@@ -114,6 +137,12 @@ export interface BindingDirective {
 // @public
 export const booleanConverter: ValueConverter;
 
+// @public (undocumented)
+export type CachedPath = DefaultCachedPath | RepeatCachedPath | AccessCachedPath | EventCachedPath;
+
+// @public (undocumented)
+export type CachedPathMap = Map<string, Map<string, JSONSchema>>;
+
 // @public
 export type Callable = typeof Function.prototype.call | {
     call(): void;
@@ -141,6 +170,14 @@ export class ChildrenDirective extends NodeObservationDirective<ChildrenDirectiv
 // @public
 export type ChildrenDirectiveOptions<T = any> = ChildListDirectiveOptions<T> | SubtreeDirectiveOptions<T>;
 
+// @public (undocumented)
+export interface ChildrenMap {
+    // (undocumented)
+    attributeName: string;
+    // (undocumented)
+    customElementName: string;
+}
+
 // @public
 export type Class<T, C = {}> = C & Constructable<T> & {
     readonly prototype: T;
@@ -248,9 +285,26 @@ export function customElement(nameOrDef: string | PartialFASTElementDefinition):
 // @public
 export type DecoratorAttributeConfiguration = Omit<AttributeConfiguration, "property">;
 
+// @public
+export function deepEqual(obj1: any, obj2: any): boolean;
+
+// @public
+export function deepMerge(target: any, source: any): boolean;
+
+// @public (undocumented)
+export interface DefaultCachedPath extends CachedPathCommon {
+    // Warning: (ae-forgotten-export) The symbol "DefaultCachedPathType" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    type: DefaultCachedPathType;
+}
+
 // @beta
 export const deferHydrationAttribute = "defer-hydration";
 
+// @public (undocumented)
+export const defsPropertyName = "$defs";
+
 // @public
 export interface Disposable {
     dispose(): void;
@@ -387,6 +441,14 @@ export interface ElementViewTemplate<TSource = any, TParent = any> {
 // @public
 export const emptyArray: readonly never[];
 
+// @public (undocumented)
+export interface EventCachedPath extends CachedPathCommon {
+    // Warning: (ae-forgotten-export) The symbol "EventCachedPathType" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    type: EventCachedPathType;
+}
+
 // @public
 export interface ExecutionContext<TParent = any> {
     readonly event: Event;
@@ -439,6 +501,16 @@ export interface ExpressionObserver<TSource = any, TReturn = any, TParent = any>
 // @public
 export const FAST: FASTGlobal;
 
+// Warning: (ae-forgotten-export) The symbol "FastContextMetaData" needs to be exported by the entry point index.d.ts
+//
+// @public (undocumented)
+export const fastContextMetaData: FastContextMetaData;
+
+// Warning: (ae-forgotten-export) The symbol "FastContextsMetaData" needs to be exported by the entry point index.d.ts
+//
+// @public (undocumented)
+export const fastContextsMetaData: FastContextsMetaData;
+
 // @public
 export interface FASTElement extends HTMLElement {
     $emit(type: string, detail?: any, options?: Omit<CustomEventInit, "detail">): boolean | void;
@@ -502,6 +574,9 @@ export interface FASTGlobal {
     warn(code: number, values?: Record<string, any>): void;
 }
 
+// @public
+export function findDef(schema: JSONSchema | JSONSchemaDefinition): string | null;
+
 // @public
 export interface HostBehavior<TSource = any> {
     addedCallback?(controller: HostController<TSource>): void;
@@ -670,6 +745,29 @@ export function isHydratable<TSource = any, TParent = any>(template: ElementView
 // @beta (undocumented)
 export function isHydratable(template: ContentTemplate): template is HydratableContentTemplate;
 
+// @public
+export function isPlainObject(value: any): value is Record<string, any>;
+
+// Warning: (ae-forgotten-export) The symbol "JSONSchemaCommon" needs to be exported by the entry point index.d.ts
+//
+// @public (undocumented)
+export interface JSONSchema extends JSONSchemaCommon {
+    // (undocumented)
+    $defs?: Record<string, JSONSchemaDefinition>;
+    // (undocumented)
+    $id: string;
+    // (undocumented)
+    $schema: string;
+}
+
+// @public (undocumented)
+export interface JSONSchemaDefinition extends JSONSchemaCommon {
+    // (undocumented)
+    $fast_context: string;
+    // (undocumented)
+    $fast_parent_contexts: Array<string>;
+}
+
 // @public
 export interface LengthObserver extends Subscriber {
     length: number;
@@ -748,6 +846,13 @@ export interface ObservationRecord {
     propertySource: any;
 }
 
+// @public
+export class ObserverMap {
+    constructor(classPrototype: any, schema: Schema, config?: ObserverMapConfig);
+    // (undocumented)
+    defineProperties(): void;
+}
+
 // @public
 export function observerMap(config?: ObserverMapConfig): FASTElementExtension;
 
@@ -827,6 +932,9 @@ export class RefDirective extends StatelessAttachedAttributeDirective<string> {
     targetNodeId: string;
 }
 
+// @public (undocumented)
+export const refPropertyName = "$ref";
+
 // @public
 export function render<TSource = any, TItem = any, TParent = any>(value?: Expression<TSource, TItem> | Binding<TSource, TItem> | {}, template?: ContentTemplate | string | Expression<TSource, ContentTemplate | string | Node, TParent> | Binding<TSource, ContentTemplate | string | Node, TParent>): CaptureType<TSource, TParent>;
 
@@ -866,6 +974,14 @@ export class RepeatBehavior<TSource = any> implements ViewBehavior, Subscriber {
     views: SyntheticView[];
 }
 
+// @public (undocumented)
+export interface RepeatCachedPath extends CachedPathCommon {
+    // Warning: (ae-forgotten-export) The symbol "RepeatCachedPathType" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    type: RepeatCachedPathType;
+}
+
 // @public
 export class RepeatDirective<TSource = any> implements HTMLDirective, ViewBehaviorFactory, BindingDirective {
     constructor(dataBinding: Binding<TSource>, templateBinding: Binding<TSource, SyntheticViewTemplate>, options: RepeatOptions);
@@ -886,6 +1002,16 @@ export interface RepeatOptions {
     recycle?: boolean;
 }
 
+// @public
+export class Schema {
+    constructor(name: string);
+    // Warning: (ae-forgotten-export) The symbol "RegisterPathConfig" needs to be exported by the entry point index.d.ts
+    addPath(config: RegisterPathConfig): void;
+    getRootProperties(): IterableIterator<string>;
+    getSchema(rootPropertyName: string): JSONSchema | null;
+    static jsonSchemaMap: CachedPathMap;
+}
+
 // @public
 export interface ShadowRootOptions extends ShadowRootInit {
     // @beta

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

@@ -90,6 +90,22 @@
       "types": "./dist/dts/observation/observable.d.ts",
       "default": "./dist/esm/observation/observable.js"
     },
+    "./extensions/observer-map.js": {
+      "types": "./dist/dts/extensions/observer-map.d.ts",
+      "default": "./dist/esm/extensions/observer-map.js"
+    },
+    "./extensions/attribute-map.js": {
+      "types": "./dist/dts/extensions/attribute-map.d.ts",
+      "default": "./dist/esm/extensions/attribute-map.js"
+    },
+    "./extensions/schema.js": {
+      "types": "./dist/dts/extensions/schema.d.ts",
+      "default": "./dist/esm/extensions/schema.js"
+    },
+    "./extensions/utilities.js": {
+      "types": "./dist/dts/extensions/utilities.d.ts",
+      "default": "./dist/esm/extensions/utilities.js"
+    },
     "./package.json": "./package.json"
   },
   "unpkg": "dist/fast-element.min.js",