Add FAST Element extension subpaths

Expose attributeMap and observerMap from extension subpaths, keep declarative re-exports, and support schema-driven usage with optional definition schemas.

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

Author: janechu

change/@microsoft-fast-element-106e0dee-a966-4f2d-9d9b-857c10599260.json

@@ -1,6 +1,6 @@
 {
   "type": "minor",
-  "comment": "Add definition-scoped declarative map extensions.",
+  "comment": "Add schema-driven attributeMap and observerMap extension subpaths, optional definition schema, and observerMap schema configuration.",
   "packageName": "@microsoft/fast-element",
   "email": "7559015+janechu@users.noreply.github.com",
   "dependentChangeType": "none"

packages/fast-element/DECLARATIVE_DESIGN.md

@@ -34,6 +34,12 @@ debug messages when they create templates. Hydratable `ViewTemplate` support is
 installed only when `enableHydration()` is called from
 `@microsoft/fast-element/hydration.js`.
 
+`observerMap()` and `attributeMap()` remain available from the declarative
+entrypoint for existing declarative imports. New code should prefer the
+extension subpaths, `@microsoft/fast-element/extensions/observer-map.js` and
+`@microsoft/fast-element/extensions/attribute-map.js`, especially when using
+the maps without declarative templates.
+
 Example:
 ```html
 <my-custom-element greeting="Hello world">
@@ -129,8 +135,15 @@ so callbacks for different elements may interleave.
 ## `observerMap`
 
 When the `observerMap()` extension is applied to an element definition,
-`@microsoft/fast-element/declarative.js` automatically sets up deep reactive
-observation for root properties discovered in the template.
+it automatically sets up deep reactive observation for root properties
+discovered in the template. Declarative templates assign `definition.schema`
+during template resolution, so `observerMap()` has schema data automatically.
+For non-declarative/manual schemas, import from the extension subpath and pass
+`observerMap({ schema })`.
+
+```typescript
+import { observerMap } from "@microsoft/fast-element/extensions/observer-map.js";
+```
 
 For finer control, pass a configuration object with a `properties` key that maps root property names to a recursive path tree:
 
@@ -181,12 +194,42 @@ When `properties` is omitted, all root properties are observed. When
 `properties` is present but empty (`{ properties: {} }`), no root properties
 are observed.
 
+Manual schema example:
+
+```typescript
+import { FASTElement, Schema } from "@microsoft/fast-element";
+import { observerMap } from "@microsoft/fast-element/extensions/observer-map.js";
+
+class MyElement extends FASTElement {}
+
+const schema = new Schema("my-element");
+schema.addPath({
+    rootPropertyName: "user",
+    pathConfig: {
+        type: "default",
+        parentContext: null,
+        currentContext: null,
+        path: "user.name",
+    },
+    childrenMap: null,
+});
+
+MyElement.define({ name: "my-element" }, [observerMap({ schema })]);
+```
+
 ## `attributeMap`
 
 When the `attributeMap()` extension is applied to an element definition,
-`@microsoft/fast-element/declarative.js` automatically creates reactive `@attr`
-properties for every **leaf binding** in the template — simple expressions like
-`{{foo}}` or `id="{{fooBar}}"` that have no nested properties.
+it automatically creates reactive `@attr` properties for every **leaf binding**
+in the template — simple expressions like `{{foo}}` or `id="{{fooBar}}"` that
+have no nested properties. Declarative templates provide the schema
+automatically. For non-declarative/manual schemas, place the optional `schema`
+on the FAST element definition and import `attributeMap()` from its extension
+subpath.
+
+```typescript
+import { attributeMap } from "@microsoft/fast-element/extensions/attribute-map.js";
+```
 
 By default, the binding key is treated as a camelCase property name and the HTML
 attribute name is derived by converting it to kebab-case. Properties already

packages/fast-element/DECLARATIVE_HTML.md

@@ -115,9 +115,12 @@ Configuration types have moved from `template.ts` to their owning modules. If yo
 | `import type { ObserverMapConfig } from "./template.js"` | `import type { ObserverMapConfig } from "./observer-map.js"` |
 | `import type { AttributeMapConfig } from "./template.js"` | `import type { AttributeMapConfig } from "./attribute-map.js"` |
 
-Public imports now come from
+Public declarative imports now come from
 `@microsoft/fast-element/declarative.js` rather than
-`@microsoft/fast-html`.
+`@microsoft/fast-html`. Existing declarative imports for `attributeMap()` and
+`observerMap()` remain valid. New code that only needs the map extensions should
+prefer `@microsoft/fast-element/extensions/attribute-map.js` and
+`@microsoft/fast-element/extensions/observer-map.js`.
 
 ### Schema changes
 
@@ -168,8 +171,45 @@ implementation is internal and is defined automatically by `declarativeTemplate(
 | `TemplateElement.config(callbacks)` / `HydrationLifecycleCallbacks` | Per-element callbacks via `declarativeTemplate(callbacks)` and global hydration callbacks via `enableHydration(options)` |
 | `TemplateElement.options({ "my-el": { attributeMap, observerMap } })` | Define extensions: `MyElement.define(definition, [attributeMap(...), observerMap(...)])` |
 | `ElementOptions` / `ElementOptionsDictionary` | No replacement |
-| `AttributeMap` / `ObserverMap` public entrypoint exports | `attributeMap()` / `observerMap()` extension helpers and their config types |
+| `AttributeMap` / `ObserverMap` class exports from the old declarative public surface | `attributeMap()` / `observerMap()` extension helpers and their config types |
 
 Hydration is also no longer installed by `@microsoft/fast-element/declarative.js`.
 Call `enableHydration()` from `@microsoft/fast-element/hydration.js` before FAST
 elements connect when prerendered Declarative Shadow DOM should be reused.
+
+## Extension subpaths and optional definition schema
+
+`attributeMap()` and `observerMap()` are now schema-driven extensions that are
+factored away from declarative templating. Prefer importing them from their
+dedicated subpaths for tree-shaken or non-declarative use:
+
+```ts
+import { attributeMap } from "@microsoft/fast-element/extensions/attribute-map.js";
+import { observerMap } from "@microsoft/fast-element/extensions/observer-map.js";
+```
+
+`FASTElementDefinition.schema` is optional. `declarativeTemplate()` assigns it
+automatically when it parses `<f-template>` markup. Manual schema users can pass
+a schema in the element definition, and `observerMap()` can also take a schema
+directly in configuration:
+
+```ts
+import { FASTElement, Schema } from "@microsoft/fast-element";
+import { observerMap } from "@microsoft/fast-element/extensions/observer-map.js";
+
+class MyElement extends FASTElement {}
+
+const schema = new Schema("my-element");
+schema.addPath({
+    rootPropertyName: "user",
+    pathConfig: {
+        type: "default",
+        parentContext: null,
+        currentContext: null,
+        path: "user.name",
+    },
+    childrenMap: null,
+});
+
+MyElement.define({ name: "my-element" }, [observerMap({ schema })]);
+```

packages/fast-element/DECLARATIVE_MIGRATION.md

@@ -1,6 +1,11 @@
 # Schema and Observer Map Architecture
 
-This document provides a technical explainer for how the `Schema` and `ObserverMap` classes work together to describe data objects and automatically observe them in FAST HTML templates using the f-template system.
+This document provides a technical explainer for how the `Schema` and
+`ObserverMap` classes work together to describe data objects and automatically
+observe them in FAST elements. Declarative `<f-template>` markup creates schemas
+automatically, but the schema and observer map implementation are factored into
+shared components and extension subpaths so they can also be used without
+declarative templating.
 
 ## Table of Contents
 
@@ -22,9 +27,10 @@ The Schema and Observer Map architecture enables automatic observation of comple
 
 ### Key Components
 
-- **Schema Class**: Generates JSON schemas that describe the structure and binding paths of data objects based on template analysis
+- **Schema Class**: Generates JSON schemas that describe the structure and binding paths of data objects based on template analysis or manually registered paths
 - **Observer Map Class**: Uses the schema information to automatically define observable properties and create proxies for nested object observation
 - **f-template Integration**: Template processing automatically populates schemas and configures observer maps during template compilation
+- **Extension Subpaths**: `@microsoft/fast-element/extensions/observer-map.js` and `@microsoft/fast-element/extensions/attribute-map.js` expose the map helpers independently from declarative templating
 
 ### Supported Data Types
 
@@ -58,7 +64,7 @@ The `Schema` class is responsible for building JSON Schema definitions that map
 ```typescript
 constructor(name: string)
 ```
-Creates a new schema instance for a specific custom element name and initializes an instance-level `schemaMap`. The instance also registers itself in the module-level `schemaRegistry` for cross-element `$ref` resolution.
+Creates a new schema instance for a specific custom element name and initializes an instance-level `schemaMap`. The instance also registers itself in the module-level `schemaRegistry` for cross-element `$ref` resolution. `FASTElementDefinition.schema` is optional; declarative templates assign it after parsing, while manual schema users can pass one in the element definition or directly to `observerMap({ schema })`.
 
 #### addPath
 ```typescript
@@ -142,9 +148,9 @@ When a root property transitions from `undefined` to a defined value, the observ
 2. Creates proxies using the `assignObservables` utility function
 3. Establishes deep observation of nested properties based on the schema of that root property
 
-## Integration with f-template
+## Integration with f-template and manual schemas
 
-The Schema and Observer Map classes integrate seamlessly with the f-template system:
+The Schema and Observer Map classes integrate seamlessly with the f-template system, but they are not tied to it:
 
 ### Template Processing Flow
 
@@ -156,10 +162,12 @@ The Schema and Observer Map classes integrate seamlessly with the f-template sys
 ### Configuration
 
 Observer Map functionality is enabled through the `observerMap()` definition
-extension:
+extension. Prefer the extension subpath for new imports; the declarative
+entrypoint continues to re-export `observerMap()` for existing declarative code:
 
 ```typescript
-import { declarativeTemplate, observerMap } from "@microsoft/fast-element/declarative.js";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+import { observerMap } from "@microsoft/fast-element/extensions/observer-map.js";
 
 MyElement.define(
   {
@@ -174,6 +182,48 @@ When the `properties` key is omitted, all root properties discovered in the
 template are observed. Add a `properties` object to opt into selective
 observation behavior.
 
+For non-declarative/manual schema use, pass the schema in the observer map
+configuration:
+
+```typescript
+import { FASTElement, Schema } from "@microsoft/fast-element";
+import { observerMap } from "@microsoft/fast-element/extensions/observer-map.js";
+
+class MyElement extends FASTElement {}
+
+const schema = new Schema("my-custom-element");
+schema.addPath({
+  rootPropertyName: "user",
+  pathConfig: {
+    type: "default",
+    parentContext: null,
+    currentContext: null,
+    path: "user.name",
+  },
+  childrenMap: null,
+});
+
+MyElement.define(
+  {
+    name: "my-custom-element",
+  },
+  [observerMap({ schema })]
+);
+```
+
+You can also attach a manual schema to the FAST element definition. This is the
+path used automatically by `declarativeTemplate()` after it parses a template:
+
+```typescript
+MyElement.define(
+  {
+    name: "my-custom-element",
+    schema,
+  },
+  [observerMap()]
+);
+```
+
 ## Initial Path Processing Flow
 
 Here's how binding paths flow through the system during initial template processing:
@@ -410,7 +460,7 @@ The schema system tracks binding contexts using special metadata:
 You can inspect generated schemas using the module-level `schemaRegistry` import:
 
 ```typescript
-import { schemaRegistry } from "@microsoft/fast-element/declarative.js";
+import { schemaRegistry } from "@microsoft/fast-element";
 
 // Get all schemas for an element:
 const elementSchemas = schemaRegistry.get('my-element');
@@ -426,8 +476,7 @@ To verify that observer mapping ran, inspect the generated schema and the
 observable accessors on the element prototype:
 
 ```typescript
-import { Observable } from "@microsoft/fast-element";
-import { schemaRegistry } from "@microsoft/fast-element/declarative.js";
+import { Observable, schemaRegistry } from "@microsoft/fast-element";
 
 const schemas = schemaRegistry.get("my-element");
 const accessors = Observable.getAccessors(MyElement.prototype).map(a => a.name);

packages/fast-element/DECLARATIVE_SCHEMA_OBSERVER_MAP.md

@@ -43,6 +43,7 @@ For deep dives into specific areas, see the linked detailed documents.
 | Reactive data binding | `Observable`, `ExpressionNotifier`, `oneWay`/`oneTime`/`listener` bindings |
 | Declarative templating | `html` tagged template literal → `ViewTemplate` → compiled `HTMLView` |
 | Declarative HTML runtime | `@microsoft/fast-element/declarative.js` → `declarativeTemplate()`, `TemplateParser`, `Schema`, `attributeMap()`, `observerMap()` |
+| Schema-driven extensions | `@microsoft/fast-element/extensions/attribute-map.js` and `@microsoft/fast-element/extensions/observer-map.js` → tree-shakeable map helpers usable with declarative or manually supplied schemas |
 | Async DOM updates | `Updates` queue (batched, `requestAnimationFrame`-aligned) |
 | Scoped styles | `css` tagged template literal → `ElementStyles` → `adoptedStylesheets` / `<style>` |
 | Dependency injection | `DI` container, `@inject`, `@singleton`, `@transient`, resolvers |
@@ -326,9 +327,14 @@ FAST Element also owns the declarative HTML runtime that previously lived in a
 separate package. The dedicated `@microsoft/fast-element/declarative.js`
 entrypoint exports the functional public API: `declarativeTemplate()`,
 `attributeMap()`, `observerMap()`, `TemplateParser`, `Schema`,
-`schemaRegistry`, and related config types. The `<f-template>` element is an
-internal native `HTMLElement` publisher that `declarativeTemplate()` defines in
-the target registry; it is not part of the public API.
+`schemaRegistry`, and related config types. Existing declarative imports remain
+supported. For consumers that only need map helpers, the preferred entrypoints
+are `@microsoft/fast-element/extensions/attribute-map.js` and
+`@microsoft/fast-element/extensions/observer-map.js`. These subpaths keep the
+schema-driven map extensions factored away from declarative templating so they
+can also be used with manually supplied schemas. The `<f-template>` element is
+an internal native `HTMLElement` publisher that `declarativeTemplate()` defines
+in the target registry; it is not part of the public API.
 
 The declarative runtime intentionally reuses the same FAST Element primitives as
 the imperative `html` API:
@@ -339,9 +345,11 @@ the imperative `html` API:
 - `TemplateParser` lowers declarative syntax to the same `strings` / `values`
   shape used by `ViewTemplate.create()`.
 - `attributeMap()` and `observerMap()` are `FASTElementExtension` factories.
-  They register schema transforms on the element definition, and those
-  transforms run after parsing in deterministic order (`attributeMap()` before
-  `observerMap()`).
+  With `declarativeTemplate()` they register schema transforms on the element
+  definition, and those transforms run after parsing in deterministic order
+  (`attributeMap()` before `observerMap()`). Outside declarative templates,
+  `attributeMap()` uses `definition.schema`, while `observerMap()` can use
+  either `definition.schema` or `observerMap({ schema })`.
 
 The `src/declarative.ts` entrypoint is pure at module evaluation time. Running a
 declarative API lazily installs declarative debug messages only. Hydration hooks
@@ -548,19 +556,24 @@ src/
 ├── components/
 │   ├── fast-element.ts    # FASTElement, @customElement
 │   ├── element-controller.ts  # ElementController, Stages
-│   ├── fast-definitions.ts    # FASTElementDefinition
+│   ├── fast-definitions.ts    # FASTElementDefinition, optional definition schema
+│   ├── schema.ts              # Schema class and schemaRegistry
+│   ├── definition-schema-transforms.ts # Definition-scoped schema transform storage
 │   └── attributes.ts          # AttributeDefinition, @attr, converters
+├── extensions/
+│   ├── observer-map.ts    # observerMap() extension and proxy-backed observation helpers
+│   └── attribute-map.ts   # attributeMap() extension and automatic @attr helpers
 ├── di/
 │   └── di.ts              # DI container, decorators, resolvers, Registration
 ├── context.ts             # Context, FASTContext, Context protocol
 ├── declarative/
 │   ├── template.ts        # declarativeTemplate() and internal f-template publisher
 │   ├── template-parser.ts # Declarative HTML parser → ViewTemplate strings/values
-│   ├── schema.ts          # Binding schema builder + schemaRegistry
-│   ├── definition-options.ts # Definition-scoped declarative schema transforms
-│   ├── observer-map.ts    # observerMap() extension and proxy-backed observation helpers
-│   ├── attribute-map.ts   # attributeMap() extension and automatic @attr helpers
-│   ├── utilities.ts       # Declarative parsing and proxy utilities
+│   ├── schema.ts          # Compatibility re-export for Schema
+│   ├── definition-options.ts # Compatibility re-export for schema transforms
+│   ├── observer-map.ts    # Compatibility re-export for observerMap()
+│   ├── attribute-map.ts   # Compatibility re-export for attributeMap()
+│   ├── utilities.ts       # Declarative parsing utilities
 │   └── syntax.ts          # Declarative syntax constants
 ├── state/
 │   ├── state.ts           # state() helper (beta)

packages/fast-element/DESIGN.md

@@ -99,7 +99,7 @@ removed `@microsoft/fast-html` package.
 | `TemplateElement.define({ name: "f-template" })` | No manual definition; `declarativeTemplate()` defines FAST's internal `<f-template>` publisher in the target registry |
 | `TemplateElement.config(callbacks)` / `HydrationLifecycleCallbacks` | Per-element callbacks via `declarativeTemplate(callbacks)` and global callbacks via `enableHydration(options)` |
 | `TemplateElement.options(...)`, `ElementOptions`, `ElementOptionsDictionary` | Define extensions: `attributeMap(...)` and `observerMap(...)` passed as the second argument to `define()` |
-| `AttributeMap` / `ObserverMap` exports from `declarative.js` | `attributeMap()` / `observerMap()` extension helpers and their config types |
+| `AttributeMap` / `ObserverMap` exports from the old declarative public surface | `attributeMap()` / `observerMap()` extension helpers and their config types |
 
 ### Migration steps
 
@@ -124,7 +124,9 @@ removed `@microsoft/fast-html` package.
 2. Replace `TemplateElement.options()` with definition extensions:
 
    ```typescript
-   import { attributeMap, declarativeTemplate, observerMap } from "@microsoft/fast-element/declarative.js";
+   import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+   import { attributeMap } from "@microsoft/fast-element/extensions/attribute-map.js";
+   import { observerMap } from "@microsoft/fast-element/extensions/observer-map.js";
 
    MyElement.define(
        {
@@ -135,6 +137,13 @@ removed `@microsoft/fast-html` package.
    );
    ```
 
+   Existing `attributeMap()` and `observerMap()` imports from
+   `@microsoft/fast-element/declarative.js` remain valid for declarative
+   templates. Prefer the extension subpaths when only the schema-driven maps are
+   needed or when using manually supplied schemas. `FASTElementDefinition.schema`
+   is optional; `declarativeTemplate()` assigns it automatically, and
+   `observerMap()` can take a manual schema with `observerMap({ schema })`.
+
 3. Replace `TemplateElement.config()` with `declarativeTemplate(callbacks)` for
    per-element callbacks and `enableHydration(options)` for global hydration
    callbacks. Hydration is not installed by `declarative.js`; call