feat: remove declarative map helper exports

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

Author: janechu

change/@microsoft-fast-element-61e3e3bd-e227-4449-9ff6-8edc104819d9.json

@@ -1,6 +1,6 @@
 {
   "type": "major",
-  "comment": "Move declarative HTML APIs into @microsoft/fast-element/declarative.js and remove the @microsoft/fast-html package.",
+  "comment": "Move declarative HTML APIs into @microsoft/fast-element/declarative.js, expose schema map helpers from extension subpaths, and remove the @microsoft/fast-html package.",
   "packageName": "@microsoft/fast-element",
   "dependentChangeType": "none",
   "email": "7559015+janechu@users.noreply.github.com"

packages/fast-element/DECLARATIVE_DESIGN.md

@@ -118,11 +118,10 @@ An optional layer that uses the `Schema` to automatically:
 - Install property-change handlers that wrap newly assigned objects/arrays in `Proxy` instances.
 - Propagate deep property mutations back through FAST's observable system so bindings re-render.
 
-Enabled via the `observerMap()` definition extension. Prefer importing the
-extension from `@microsoft/fast-element/extensions/observer-map.js`; the
-declarative entrypoint continues to re-export it for existing declarative
-imports. Calling `observerMap()` without arguments observes all root properties
-discovered in the template or supplied schema.
+Enabled via the `observerMap()` definition extension. Import the extension from
+`@microsoft/fast-element/extensions/observer-map.js`; the declarative entrypoint
+does not re-export it. Calling `observerMap()` without arguments observes all
+root properties discovered in the template or supplied schema.
 
 #### Path-level observation control
 
@@ -202,12 +201,11 @@ An optional layer that uses the `Schema` to automatically register `@attr`-style
 - Properties already decorated with `@attr` or `@observable` are left untouched.
 - `FASTElementDefinition.attributeLookup` is keyed by the HTML attribute name, and `propertyLookup` is keyed by the JS property name so `attributeChangedCallback` correctly delegates to the new `AttributeDefinition`.
 
-Enabled via the `attributeMap()` definition extension. Prefer importing the
-extension from `@microsoft/fast-element/extensions/attribute-map.js`; the
-declarative entrypoint continues to re-export it for existing declarative
-imports. Calling `attributeMap()` without arguments uses the default
-`"camelCase"` strategy. To preserve binding keys exactly as written, pass
-`attributeMap({ "attribute-name-strategy": "none" })`. Outside declarative
+Enabled via the `attributeMap()` definition extension. Import the extension from
+`@microsoft/fast-element/extensions/attribute-map.js`; the declarative entrypoint
+does not re-export it. Calling `attributeMap()` without arguments uses the
+default `"camelCase"` strategy. To preserve binding keys exactly as written,
+pass `attributeMap({ "attribute-name-strategy": "none" })`. Outside declarative
 templates, `attributeMap()` uses the optional `schema` on the FAST element
 definition.
 
@@ -249,8 +247,8 @@ packages/fast-element/
 │       ├── template-bridge.ts # Registry/name bridge between definitions and publishers
 │       ├── template-parser.ts # TemplateParser — converts declarative HTML to ViewTemplate strings/values
 │       ├── schema.ts          # Compatibility re-export for Schema
-│       ├── observer-map.ts    # Compatibility re-export for observerMap()
-│       ├── attribute-map.ts   # Compatibility re-export for attributeMap()
+│       ├── observer-map.ts    # Internal observer-map extension alias (not a package export)
+│       ├── attribute-map.ts   # Internal attribute-map extension alias (not a package export)
 │       ├── utilities.ts       # Declarative parsing helpers
 │       └── syntax.ts          # Syntax delimiter constants
 ├── scripts/
@@ -307,43 +305,54 @@ import {
 } from "@microsoft/fast-element/extensions/observer-map.js";
 ```
 
-`@microsoft/fast-element/declarative.js` still re-exports `attributeMap()`,
-`observerMap()`, and their configuration types for existing declarative imports.
-The extension subpaths are preferred when a consumer only needs the maps or is
-using manually supplied schemas.
+The declarative entrypoint does not re-export the map helpers or their
+configuration types. Use the extension subpaths whether the maps are paired with
+declarative templates or manually supplied schemas.
 
-Primary exports intended for application code:
+Primary exports from `@microsoft/fast-element/declarative.js` intended for
+application code:
 
 | Export | Purpose |
 |---|---|
 | `declarativeTemplate()` | Template resolver for `FASTElement.define()`; auto-defines the internal `<f-template>` publisher and waits for the matching template. |
-| `attributeMap()` | Define extension that registers `@attr`-style properties for leaf bindings discovered during parsing or supplied by `definition.schema`. |
-| `observerMap()` | Define extension that defines observable root properties and proxy-based deep change tracking from `config.schema`, `definition.schema`, or a declarative template schema. |
 | `TemplateParser` | Standalone parser that converts declarative HTML into `ViewTemplate` strings/values. Can be used independently of `<f-template>` for programmatic template compilation. |
 | `Schema` | JSON schema builder that records binding paths discovered during template parsing. Each instance owns its own schema map and registers itself in the `schemaRegistry` for cross-element `$ref` resolution. |
 | `schemaRegistry` | Module-level `Map<string, Map<string, JSONSchema>>` that indexes schemas by custom element name. Used for cross-element lookups (e.g. nested component `$ref` resolution). |
 
+Primary map extension exports:
+
+| Export | Public subpath | Purpose |
+|---|---|---|
+| `attributeMap()` | `@microsoft/fast-element/extensions/attribute-map.js` | Define extension that registers `@attr`-style properties for leaf bindings discovered during parsing or supplied by `definition.schema`. |
+| `observerMap()` | `@microsoft/fast-element/extensions/observer-map.js` | Define extension that defines observable root properties and proxy-based deep change tracking from `config.schema`, `definition.schema`, or a declarative template schema. |
+
 The implementation element class (`<f-template>`), `TemplateElement.config()`,
 `TemplateElement.options()`, `ElementOptions*`, and
 `HydrationLifecycleCallbacks` are not exported from the public declarative
-entrypoint. Use `declarativeTemplate()`, `attributeMap()`, `observerMap()`, and
-`enableHydration()` instead. The `AttributeMap` and `ObserverMap` implementation
-classes are available from their extension subpaths for advanced scenarios, but
-application code should normally use the extension factories.
+entrypoint. Use `declarativeTemplate()`, extension subpath `attributeMap()` and
+`observerMap()`, and `enableHydration()` instead. The `AttributeMap` and
+`ObserverMap` implementation classes are available from their extension subpaths
+for advanced scenarios, but application code should normally use the extension
+factories.
 
-Additionally, the following types are exported:
+Additionally, `@microsoft/fast-element/declarative.js` exports these types:
 
 | Type | Source Module | Purpose |
 |---|---|---|
 | `FASTElementExtension` | `fast-definitions.ts` | Definition extension callback signature used by `attributeMap()` and `observerMap()`. |
 | `TemplateLifecycleCallbacks` | `fast-definitions.ts` | Per-element lifecycle callbacks accepted by `declarativeTemplate()`. |
-| `ObserverMapConfig` | `extensions/observer-map.ts` | Configuration object for `observerMap()`; accepts optional `schema` and `properties` keys. |
-| `ObserverMapPathEntry` | `observer-map.ts` | `boolean \| ObserverMapPathNode` — a node in the observation path tree. |
-| `ObserverMapPathNode` | `observer-map.ts` | Object node with optional `$observe` and child property overrides. |
-| `AttributeMapConfig` | `extensions/attribute-map.ts` | Configuration object for `attributeMap()`; accepts `attribute-name-strategy`. |
 | `JSONSchema` | `components/schema.ts` | JSON Schema interface used by `Schema` for property structure. |
 | `CachedPathMap` | `components/schema.ts` | `Map<string, Map<string, JSONSchema>>` — the shape of the schema registry. |
 
+The extension subpaths export their own configuration types:
+
+| Type | Public subpath | Purpose |
+|---|---|---|
+| `ObserverMapConfig` | `@microsoft/fast-element/extensions/observer-map.js` | Configuration object for `observerMap()`; accepts optional `schema` and `properties` keys. |
+| `ObserverMapPathEntry` | `@microsoft/fast-element/extensions/observer-map.js` | `boolean \| ObserverMapPathNode` — a node in the observation path tree. |
+| `ObserverMapPathNode` | `@microsoft/fast-element/extensions/observer-map.js` | Object node with optional `$observe` and child property overrides. |
+| `AttributeMapConfig` | `@microsoft/fast-element/extensions/attribute-map.js` | Configuration object for `attributeMap()`; accepts `attribute-name-strategy`. |
+
 ---
 
 ## Template Syntax

packages/fast-element/DESIGN.md

@@ -42,7 +42,7 @@ For deep dives into specific areas, see the linked detailed documents.
 | Element authoring | `FASTElement` base class + `@customElement`, `@attr`, `@observable` decorators |
 | 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()` |
+| Declarative HTML runtime | `@microsoft/fast-element/declarative.js` → `declarativeTemplate()`, `TemplateParser`, `Schema` |
 | 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>` |
@@ -325,16 +325,14 @@ See `docs/di/api-report.api.md` for the full public API surface.
 
 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. 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.
+entrypoint exports the declarative runtime API: `declarativeTemplate()`,
+`TemplateParser`, `Schema`, `schemaRegistry`, and related parser/schema types.
+Import map helpers from `@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:
@@ -344,12 +342,13 @@ the imperative `html` API:
   bridge.
 - `TemplateParser` lowers declarative syntax to the same `strings` / `values`
   shape used by `ViewTemplate.create()`.
-- `attributeMap()` and `observerMap()` are `FASTElementExtension` factories.
-  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 })`.
+- `attributeMap()` and `observerMap()` are `FASTElementExtension` factories
+  exported from dedicated extension subpaths. 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
@@ -571,8 +570,8 @@ src/
 │   ├── template-parser.ts # Declarative HTML parser → ViewTemplate strings/values
 │   ├── 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()
+│   ├── observer-map.ts    # Internal observer-map extension alias (not a package export)
+│   ├── attribute-map.ts   # Internal attribute-map extension alias (not a package export)
 │   ├── utilities.ts       # Declarative parsing utilities
 │   └── syntax.ts          # Declarative syntax constants
 ├── state/

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

@@ -10,14 +10,6 @@ export interface AccessCachedPath extends CachedPathCommon {
     type: "access";
 }
 
-// @public
-export function attributeMap(config?: AttributeMapConfig): FASTElementExtension;
-
-// @public
-export interface AttributeMapConfig {
-    "attribute-name-strategy"?: "none" | "camelCase";
-}
-
 // @public
 export type CachedPath = DefaultCachedPath | RepeatCachedPath | AccessCachedPath | EventCachedPath;
 
@@ -97,28 +89,6 @@ export interface JSONSchemaDefinition extends JSONSchemaCommon {
     $fast_parent_contexts: Array<string>;
 }
 
-// @public
-export function observerMap(config?: ObserverMapConfig): FASTElementExtension;
-
-// @public
-export interface ObserverMapConfig {
-    properties?: {
-        [rootProperty: string]: ObserverMapPathEntry;
-    };
-    schema?: Schema;
-}
-
-// @public
-export type ObserverMapPathEntry = boolean | ObserverMapPathNode;
-
-// @public
-export interface ObserverMapPathNode {
-    // (undocumented)
-    $observe?: boolean;
-    // (undocumented)
-    [propertyName: string]: ObserverMapPathEntry | undefined;
-}
-
 // @public
 export interface RegisterPathConfig {
     // (undocumented)

packages/fast-element/src/declarative/index.ts

@@ -2,13 +2,6 @@ export type {
     FASTElementExtension,
     TemplateLifecycleCallbacks,
 } from "../components/fast-definitions.js";
-export { type AttributeMapConfig, attributeMap } from "./attribute-map.js";
-export type {
-    ObserverMapConfig,
-    ObserverMapPathEntry,
-    ObserverMapPathNode,
-} from "./observer-map.js";
-export { observerMap } from "./observer-map.js";
 export {
     type AccessCachedPath,
     type CachedPath,

packages/fast-element/src/declarative/template-bridge.pw.spec.ts

@@ -180,6 +180,25 @@ test.describe("declarativeTemplate", () => {
         expect(result.declarativeTemplateAfterHydration).toBe(true);
     });
 
+    test("does not export map helpers from declarative entrypoint", async ({ page }) => {
+        await page.goto("/");
+
+        const result = await page.evaluate(async pureEntrypointUrl => {
+            // @ts-expect-error: Client module.
+            const declarative = await import(pureEntrypointUrl);
+
+            return {
+                hasAttributeMap: "attributeMap" in declarative,
+                hasObserverMap: "observerMap" in declarative,
+            };
+        }, pureDeclarativeEntrypointUrl);
+
+        expect(result).toEqual({
+            hasAttributeMap: false,
+            hasObserverMap: false,
+        });
+    });
+
     test("does not bundle map modules for plain declarativeTemplate", async () => {
         const result = await build({
             stdin: {
@@ -232,11 +251,13 @@ test.describe("declarativeTemplate", () => {
             const {
                 FASTElement,
                 FASTElementDefinition,
-                attributeMap,
                 declarativeTemplate,
-                observerMap,
                 uniqueElementName,
             } = await import("/declarative-main.js");
+            // @ts-expect-error: Client module.
+            const { attributeMap, observerMap } = await import(
+                "/extension-subpaths-main.js"
+            );
 
             const elementName = uniqueElementName();
 

packages/fast-element/test/declarative/fixtures/bindings/dot-syntax/main.ts

@@ -1,5 +1,6 @@
 import { FASTElement } from "@microsoft/fast-element";
-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";
 import { enableHydration } from "@microsoft/fast-element/hydration.js";
 
 class TestElement extends FASTElement {

packages/fast-element/test/declarative/fixtures/directives/repeat/main.ts

@@ -1,6 +1,7 @@
 import { attr, FASTElement, observable } from "@microsoft/fast-element";
 import { deepMerge } from "@microsoft/fast-element/declarative/utilities.js";
-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";
 import { enableHydration } from "@microsoft/fast-element/hydration.js";
 
 export class TestElement extends FASTElement {

packages/fast-element/test/declarative/fixtures/ecosystem/lifecycle-callbacks/main.ts

@@ -1,5 +1,6 @@
 import { attr, FASTElement, observable } from "@microsoft/fast-element";
-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";
 import { enableHydration } from "@microsoft/fast-element/hydration.js";
 
 // Track lifecycle callbacks for testing

packages/fast-element/test/declarative/fixtures/extensions/attribute-map-naming-strategy/main.ts

@@ -1,8 +1,6 @@
 import { FASTElement } from "@microsoft/fast-element";
-import {
-    attributeMap,
-    declarativeTemplate,
-} from "@microsoft/fast-element/declarative.js";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+import { attributeMap } from "@microsoft/fast-element/extensions/attribute-map.js";
 
 class NamingStrategyTestElement extends FASTElement {}