docs(fast-element): fix v3 migration guidance

packages/fast-element/MIGRATION.md

@@ -20,33 +20,38 @@
 2. Fix duplicate FAST installs in your bundler or dependency graph instead of relying on version tracking at runtime.
 3. Remove any `fast-kernel` script attributes. They no longer affect FAST initialization.
 
-## Native `globalThis` requirement (v2 → v3)
+## Native globals and scheduler requirements (v2 → v3)
 
 ### Changed behavior
 
 - **Native `globalThis` required**: `@microsoft/fast-element` no longer installs
-  a `globalThis` polyfill as a side effect. The package only keeps the
-  `requestIdleCallback` / `cancelIdleCallback` fallback for environments that
-  still lack those APIs.
+  a `globalThis` polyfill as a side effect.
+- **No idle-callback polyfill**: FAST Element v3 no longer installs or depends
+  on a `requestIdleCallback` / `cancelIdleCallback` fallback. The async
+  `Updates` queue schedules work with `globalThis.requestAnimationFrame`.
 
 ### Migration steps
 
 1. Verify that the browsers and JS runtimes you support provide native
-   `globalThis`.
-2. If you still target an older runtime without `globalThis`, load that
-   polyfill before importing `@microsoft/fast-element`.
+   `globalThis` and, when using async DOM updates, `requestAnimationFrame`.
+2. If you still target an older runtime without `globalThis` or
+   `requestAnimationFrame`, load those polyfills before importing
+   `@microsoft/fast-element`.
+3. You do not need to polyfill `requestIdleCallback` or `cancelIdleCallback`
+   for FAST Element itself. Only provide them if your application or another
+   dependency calls those APIs directly.
 
 ## Declarative HTML moved into fast-element (v3)
 
-Declarative HTML APIs now ship from `@microsoft/fast-element` instead of the
-removed `@microsoft/fast-html` package.
+Declarative HTML APIs now ship from focused `@microsoft/fast-element` package
+path exports instead of the removed `@microsoft/fast-html` package.
 
 ### Import changes
 
 | Before | After |
 |---|---|
-| `@microsoft/fast-html` | `@microsoft/fast-element` |
-| `@microsoft/fast-html/utilities.js` | `@microsoft/fast-element` |
+| `@microsoft/fast-html` | `@microsoft/fast-element/declarative.js` |
+| `@microsoft/fast-html/utilities.js` | `@microsoft/fast-element/declarative-utilities.js` |
 
 Core FAST Element helpers are available from the root package export:
 
@@ -62,7 +67,7 @@ Core FAST Element helpers are available from the root package export:
 | `html`, `ViewTemplate`, `HTMLView` | `@microsoft/fast-element` |
 | `Compiler`, `HTMLDirective`, `htmlDirective`, templating/view types | `@microsoft/fast-element` |
 | `render`, `RenderBehavior`, `RenderDirective` | `@microsoft/fast-element` |
-| `enableHydration`, `HydrationTracker`, hydration types | `@microsoft/fast-element/hydration.js` |
+| `enableHydration`, `deferHydrationAttribute`, `HydrationTracker`, hydration types | `@microsoft/fast-element/hydration.js` |
 | `ArrayObserver` | `@microsoft/fast-element` |
 | `volatile` | `@microsoft/fast-element` |
 | `children` | `@microsoft/fast-element` |
@@ -207,20 +212,21 @@ data source.
 
 ## Prerendered Content Optimization (v2 → v3)
 
-### Removed exports
+### Removed and moved APIs
 
-| Export | Replacement |
+| 2.x API | 3.x guidance |
 |---|---|
 | `HydratableElementController` | `ElementController` (prerendered path built in) |
-| `HydrationControllerCallbacks` | `ElementHydrationCallbacks` via `ElementController.configHydration()` |
-| `needsHydrationAttribute` | `ElementController.isPrerendered` |
-| `deferHydrationAttribute` | Template-pending guard in `ElementController.connect()` |
+| `HydrationControllerCallbacks` | Global callbacks via `enableHydration(options)`; per-element callbacks via `declarativeTemplate(callbacks)` |
+| `needsHydrationAttribute` | No replacement. Existing shadow root detection sets `ElementController.isPrerendered`. |
+| Root `deferHydrationAttribute` export | Import `deferHydrationAttribute` from `@microsoft/fast-element/hydration.js` only if you still need the legacy attribute string. New server-rendered markup should omit `defer-hydration`. |
 
 ### Removed side-effect imports
 
 | Import | Replacement |
 |---|---|
 | `@microsoft/fast-element/install-hydration.js` | No replacement needed — prerendered path is built into `ElementController` |
+| `@microsoft/fast-element/install-hydratable-view-templates.js` | No replacement needed — `enableHydration()` installs hydratable template support |
 
 Use `enableHydration()` from `@microsoft/fast-element/hydration.js` when SSR
 content should hydrate. The declarative entrypoint no longer installs hydration
@@ -236,8 +242,10 @@ automatically.
 
 ### New APIs
 
-- **`ElementController.isPrerendered`** (`Promise<boolean>`): Resolves to `true` after prerendered content has been hydrated, or `false` when the component is client-side rendered. Component authors can await this to know when the element is fully interactive.
+- **`ElementController.isPrerendered`** (`Promise<boolean>`): Resolves to `true` when the element had a declarative shadow root at connect time, or `false` when the component was client-side rendered.
+- **`ElementController.isHydrated`** (`Promise<boolean>`): Resolves to `true` only when hydration ran successfully.
 - **`ViewController.isPrerendered`** (`Promise<boolean> | undefined`): Available to custom directives. Resolves to `true` when the view's content was prerendered, `false` otherwise.
+- **`ViewController.isHydrated`** (`Promise<boolean> | undefined`): Available to custom directives. Resolves to `true` only when hydration ran successfully.
 
 ### Migration steps
 

packages/fast-element/docs/declarative-html.md

@@ -32,11 +32,12 @@ The `@microsoft/fast-element` entrypoint itself remains
 side-effect free at import time. Declarative APIs lazily install declarative
 debug messages when they create templates. Hydratable `ViewTemplate` support is
 installed only when `enableHydration()` is called from
-`@microsoft/fast-element`.
+`@microsoft/fast-element/hydration.js`.
 
 `observerMap()` and `attributeMap()` are available from
-`@microsoft/fast-element`, including when using the maps without declarative
-templates.
+`@microsoft/fast-element/observer-map.js` and
+`@microsoft/fast-element/attribute-map.js`, including when using the maps
+without declarative templates.
 
 Example:
 ```html
@@ -136,8 +137,8 @@ When the `observerMap()` extension is applied to an element definition,
 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 `@microsoft/fast-element` and
-pass `observerMap({ schema })`.
+For non-declarative/manual schemas, import from
+`@microsoft/fast-element/observer-map.js` and pass `observerMap({ schema })`.
 
 ```typescript
 import { observerMap } from "@microsoft/fast-element/observer-map.js";

packages/fast-element/docs/declarative-migration.md

@@ -116,11 +116,11 @@ Configuration types have moved from `template.ts` to their owning modules. If yo
 | `import type { AttributeMapConfig } from "./template.js"` | `import type { AttributeMapConfig } from "./attribute-map.js"` |
 
 Public declarative imports now come from
-`@microsoft/fast-element` rather than
-`@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` and
-`@microsoft/fast-element`.
+`@microsoft/fast-element/declarative.js` rather than
+`@microsoft/fast-html`, and declarative utilities come from
+`@microsoft/fast-element/declarative-utilities.js`. Map extensions come from
+`@microsoft/fast-element/attribute-map.js` and
+`@microsoft/fast-element/observer-map.js`.
 
 ### Schema changes
 

sites/website/src/docs/3.x/migration-guide.md

@@ -38,12 +38,11 @@ enableHydration();
 
 Remove any `import "@microsoft/fast-element/install-hydration.js"` side-effect
 imports as part of the migration. The older
-`install-hydratable-view-templates.js` helper remains available for advanced
-use cases, but the preferred API is `enableHydration()`.
-`@microsoft/fast-element` no longer installs hydration
-automatically.
+`install-hydratable-view-templates.js` side-effect helper should also be
+removed; `enableHydration()` installs hydratable template support.
+`@microsoft/fast-element` no longer installs hydration automatically.
 
-### `needsHydrationAttribute` and `deferHydrationAttribute` removed
+### `needs-hydration` and `defer-hydration` markup no longer required
 
 These attributes are no longer needed in server-rendered markup.
 
@@ -115,7 +114,7 @@ connectedCallback() {
 ### Declarative HTML imports moved
 
 The `@microsoft/fast-html` package has been removed. Import declarative HTML
-APIs from the FAST Element root package instead:
+APIs from FAST Element path exports instead:
 
 ```ts
 // Before
@@ -142,7 +141,7 @@ definition/controller types, and helper APIs from `@microsoft/fast-element`:
 | `html`, `ViewTemplate`, `HTMLView` | `@microsoft/fast-element` |
 | `Compiler`, `HTMLDirective`, `htmlDirective`, templating/view types | `@microsoft/fast-element` |
 | `render`, `RenderBehavior`, `RenderDirective` | `@microsoft/fast-element` |
-| `enableHydration`, `HydrationTracker`, hydration types | `@microsoft/fast-element/hydration.js` |
+| `enableHydration`, `deferHydrationAttribute`, `HydrationTracker`, hydration types | `@microsoft/fast-element/hydration.js` |
 | `ArrayObserver` | `@microsoft/fast-element` |
 | `volatile` | `@microsoft/fast-element` |
 | `children` | `@microsoft/fast-element` |
@@ -167,8 +166,8 @@ when an element uses `template: declarativeTemplate()`.
 | `TemplateElement.options(...)` | `attributeMap()` and `observerMap()` define extensions |
 | `AttributeMap` / `ObserverMap` class exports from the old declarative public surface | `attributeMap()` / `observerMap()` helpers and config types |
 
-Import `declarativeTemplate()` and schema-driven map extensions from
-`@microsoft/fast-element`:
+Import `declarativeTemplate()` and schema-driven map extensions from their
+focused path exports:
 
 ```ts
 import { attributeMap } from "@microsoft/fast-element/attribute-map.js";
@@ -333,9 +332,11 @@ Update imports to:
 import { ArrayObserver } from "@microsoft/fast-element";
 ```
 
-### `deferHydrationAttribute` moved to `@microsoft/fast-element`
+### `deferHydrationAttribute` moved to `@microsoft/fast-element/hydration.js`
 
-`deferHydrationAttribute` is available from the root package export.
+`deferHydrationAttribute` is no longer exported by the root package. Most apps
+can remove `defer-hydration` from server-rendered markup; if you still need the
+legacy attribute string, import it from the hydration path export.
 
 2.x imported `deferHydrationAttribute` from the root package.
 
@@ -346,12 +347,16 @@ const attribute = "defer-hydration";
 
 3.x Example:
 ```ts
-import { deferHydrationAttribute } from "@microsoft/fast-element";
+import { deferHydrationAttribute } from "@microsoft/fast-element/hydration.js";
 ```
 
-### `requestIdleCallback` polyfill removed
+### `requestIdleCallback` / `cancelIdleCallback` polyfill removed
 
-The built-in `requestIdleCallback` / `cancelIdleCallback` polyfill has been removed. If your application targets environments without these APIs, provide your own polyfill.
+FAST Element v3 no longer installs or depends on a `requestIdleCallback` /
+`cancelIdleCallback` fallback. You do not need to polyfill those APIs for FAST
+Element itself. The async `Updates` queue schedules DOM work with
+`requestAnimationFrame`, so provide a `requestAnimationFrame` polyfill before
+importing FAST Element when running in a non-browser environment that lacks it.
 
 ### Hydration marker format changed
 
@@ -431,6 +436,7 @@ For `mode: "boolean"`, FAST writes attributes via `DOM.setBooleanAttribute` (pre
 | `ElementController.isPrerendered` | `fast-element` | `Promise<boolean>` — resolves `true` when element had DSD at connect time |
 | `ElementController.isHydrated` | `fast-element` | `Promise<boolean>` — resolves `true` only when hydration ran successfully |
 | `enableHydration()` | `fast-element/hydration.js` | Enables hydration support for FAST elements |
+| `deferHydrationAttribute` | `fast-element/hydration.js` | Legacy `defer-hydration` attribute string for compatibility code |
 | `HydrationTracker` | `fast-element/hydration.js` | Standalone hydration lifecycle tracker class |
 | `HydrationOptions` | `fast-element/hydration.js` | Type for hydration configuration options |
 | `ViewController.isPrerendered` | `fast-element/templating.js` | `Promise<boolean>` — DSD detection for custom directives |