From 7cdb39c2761f7951691499dd332f81c830d5162e Mon Sep 17 00:00:00 2001 From: Jane Chu <7559015+janechu@users.noreply.github.com> Date: Fri, 29 May 2026 14:28:13 -0700 Subject: [PATCH] docs(fast-element): fix v3 migration guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- packages/fast-element/MIGRATION.md | 44 +++++++++++-------- .../fast-element/docs/declarative-html.md | 11 ++--- .../docs/declarative-migration.md | 10 ++--- sites/website/src/docs/3.x/migration-guide.md | 34 ++++++++------ 4 files changed, 57 insertions(+), 42 deletions(-) diff --git a/packages/fast-element/MIGRATION.md b/packages/fast-element/MIGRATION.md index a36f369d1d3..a54dec76926 100644 --- a/packages/fast-element/MIGRATION.md +++ b/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`): 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`): 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`): Resolves to `true` only when hydration ran successfully. - **`ViewController.isPrerendered`** (`Promise | undefined`): Available to custom directives. Resolves to `true` when the view's content was prerendered, `false` otherwise. +- **`ViewController.isHydrated`** (`Promise | undefined`): Available to custom directives. Resolves to `true` only when hydration ran successfully. ### Migration steps diff --git a/packages/fast-element/docs/declarative-html.md b/packages/fast-element/docs/declarative-html.md index 254561718fe..9fe4818d13a 100644 --- a/packages/fast-element/docs/declarative-html.md +++ b/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"; diff --git a/packages/fast-element/docs/declarative-migration.md b/packages/fast-element/docs/declarative-migration.md index 972bf260b15..a85b913085c 100644 --- a/packages/fast-element/docs/declarative-migration.md +++ b/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 diff --git a/sites/website/src/docs/3.x/migration-guide.md b/sites/website/src/docs/3.x/migration-guide.md index b87d4bf6ce2..1e4f0c7e01f 100644 --- a/sites/website/src/docs/3.x/migration-guide.md +++ b/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` — resolves `true` when element had DSD at connect time | | `ElementController.isHydrated` | `fast-element` | `Promise` — 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` — DSD detection for custom directives |