@microsoft/fast-element 2.10.4 → 3.0.0-rc.2

package/CHANGELOG.md

@@ -1,12 +1,62 @@
 # Change Log - @microsoft/fast-element
 
-<!-- This log was last generated on Fri, 17 Apr 2026 00:26:33 GMT and should not be manually modified. -->
+<!-- This log was last generated on Fri, 19 Jun 2026 22:15:55 GMT and should not be manually modified. -->
 
 <!-- Start content -->
 
+## 3.0.0-rc.2
+
+Fri, 19 Jun 2026 22:15:55 GMT
+
+### Changes
+
+- Filter late attribute MutationObserver records. (7559015+janechu@users.noreply.github.com)
+- fix: align @attr({ mode: 'boolean' }) and booleanConverter with native HTML boolean attribute semantics (7559015+janechu@users.noreply.github.com)
+- feat: expose declarative HTML syntax constants from declarative utilities (7559015+janechu@users.noreply.github.com)
+- fix: restore CaptureType generic type capture for template directives (7559015+janechu@users.noreply.github.com)
+- feat: change default attribute-name-strategy from none to camelCase (7559015+janechu@users.noreply.github.com)
+- feat: auto-escape `{` and `}` inside `<code>` elements so binding-like syntax in code samples renders as literal text (mirrors webui-press and the server-side `escape_code_sample_elements` pass in `@microsoft/fast-build`, which additionally handles `<f-when>`/`<f-repeat>` directive tags) (7559015+janechu@users.noreply.github.com)
+- Improve hydration mismatch behaviour: render() falls back to client rendering when SSR view boundaries are empty, repeat() reconciles SSR/client item-count mismatches by creating missing client views or removing extra SSR ranges, and unrecoverable mismatches throw via a pluggable HydrationDiagnostic. Opt in to the rich 'Expected / Received' format with the SSR HTML snippet and structured expected/received fields on HydrationBindingError / HydrationTargetElementError by passing enableHydration({ debugger: hydrationDebugger() }) (hydrationDebugger is exported from '@microsoft/fast-element/hydration.js'). (7559015+janechu@users.noreply.github.com)
+- Add hydration configuration for streamed Declarative Shadow DOM. (7559015+janechu@users.noreply.github.com)
+- Avoid mutating render template bindings (7559015+janechu@users.noreply.github.com)
+- feat: propagate shadowroot attributes from f-template to declarative shadow DOM template (7559015+janechu@users.noreply.github.com)
+- Preserve view context when rebinding the same source. (7559015+janechu@users.noreply.github.com)
+- feat: warn when duplicate render instruction registrations replace existing entries (7559015+janechu@users.noreply.github.com)
+- Add a registry path export for FAST element definition lookups. (7559015+janechu@users.noreply.github.com)
+- Bump @microsoft/fast-build to v0.8.0-fast-element-v3-rc-20260615
+
+## 3.0.0-rc.1
+
+Tue, 28 Apr 2026 04:42:02 GMT
+
+### Major changes
+
+- remove FASTGlobal version tracking (7559015+janechu@users.noreply.github.com)
+- Remove hydration view template side effect and unused export paths (7559015+janechu@users.noreply.github.com)
+- Move optional helpers to dedicated flat fast-element subpath exports such as @microsoft/fast-element/children.js, @microsoft/fast-element/repeat.js, @microsoft/fast-element/two-way.js, @microsoft/fast-element/signal.js, @microsoft/fast-element/attribute-map.js, and @microsoft/fast-element/observer-map.js while keeping controller and definition internals on the root entrypoint. (7559015+janechu@users.noreply.github.com)
+- Remove the public declarative TemplateElement configuration APIs and make declarative templates use an internal native f-template publisher with explicit hydration opt-in. (7559015+janechu@users.noreply.github.com)
+- Replace HydratableElementController with automatic prerendered content optimization. When a component connects with an existing shadow root, bindings skip attribute/booleanAttribute DOM updates during initial render while still setting up event listeners, observers, and dependency tracking. Added isPrerendered flag to ElementController and ViewController. Added template-pending guard for defineAsync flow. (7559015+janechu@users.noreply.github.com)
+- Move declarative HTML APIs into @microsoft/fast-element/declarative.js, expose schema map helpers from extension subpaths, and remove the @microsoft/fast-html package. (7559015+janechu@users.noreply.github.com)
+- Remove ElementStyles.withBehaviors, CSS style behaviors, and CSS bindings in fast-element. (7559015+janechu@users.noreply.github.com)
+- Remove TemplateOptions from fast-element definitions and drop templateOptions-based connection/define waiting. (7559015+janechu@users.noreply.github.com)
+- Simplify hydration markers to data-free sequential format (fe:b, fe:/b, fe:r, fe:/r, fe:e, fe:/e). Replace regex parsing with string equality checks. Single data-fe attribute replaces three old formats. Breaking change: SSR output format changed. (7559015+janechu@users.noreply.github.com)
+- remove deprecated declarative event e support (7559015+janechu@users.noreply.github.com)
+- Make declarative runtime setup lazy and change @microsoft/fast-element/debug.js to require an explicit enableDebug() call. (7559015+janechu@users.noreply.github.com)
+- Remove defineAsync and composeAsync — define() and compose() now return Promises (7559015+janechu@users.noreply.github.com)
+- Remove the built-in globalThis polyfill; fast-element v3 now requires native globalThis (7559015+janechu@users.noreply.github.com)
+- fix: remove the fast-kernel multi-kernel modes. Breaking change: FAST no longer supports configuring isolated or version-scoped kernels via the script attribute. (7559015+janechu@users.noreply.github.com)
+
+### Minor changes
+
+- Add schema-driven attributeMap and observerMap extension subpaths, optional definition schema, and observerMap schema configuration. (7559015+janechu@users.noreply.github.com)
+- add declarativeTemplate for auto-resolving <f-template> markup (7559015+janechu@users.noreply.github.com)
+- Add extensions array argument to FASTElement.define() and FASTElementDefinition.define() (7559015+janechu@users.noreply.github.com)
+- feat: modularize hydration and expose lifecycle callbacks via enableHydration() and declarativeTemplate() (7559015+janechu@users.noreply.github.com)
+- add function-based template resolver sequencing (7559015+janechu@users.noreply.github.com)
+
 ## 2.10.4
 
-Fri, 17 Apr 2026 00:26:33 GMT
+Fri, 17 Apr 2026 00:26:37 GMT
 
 ### Patches
 

package/README.md

@@ -51,4 +51,247 @@ For simplicity, examples throughout the documentation will assume the library ha
 
 :::tip
 Looking for a quick guide on building components?  Check out [our Cheat Sheet](../resources/cheat-sheet.md#building-components).
-:::
+:::
+
+## Browser Requirements
+
+FAST Element v3 assumes a client-side browser `Window` runtime with native
+`globalThis`, Custom Elements, DOM, Shadow DOM, and `requestAnimationFrame`.
+The `FAST` object is now a module-scoped export (not on `globalThis`). If you
+need to support an older browser without `globalThis`, load that polyfill before
+importing `@microsoft/fast-element`.
+
+The FAST Element client runtime is not intended to execute in workers,
+server-side JavaScript runtimes, or other non-window hosts. Use server-side
+rendering tools to produce HTML for the browser, and run FAST Element in the
+client window where custom elements connect, render, update, and hydrate.
+
+## Debug entrypoint
+
+`@microsoft/fast-element/debug.js` exports `enableDebug()` instead of configuring
+FAST at import time. The development root export and debug rollup bundle still
+enable debug behavior automatically.
+
+```ts
+import { enableDebug } from "@microsoft/fast-element/debug.js";
+
+enableDebug();
+```
+
+## Export Sizes
+
+Bundle sizes for each tree-shakeable export are tracked in [`SIZES.md`](./SIZES.md) and regenerated on every build. See the [Export Sizes](https://www.fast.design/docs/2.x/resources/export-sizes/) documentation page for the latest numbers.
+
+## Root Imports and Path Exports
+
+The root `@microsoft/fast-element` entrypoint exports the FAST Element
+implementation APIs, including the element base class, kernel, controller,
+definition APIs, template APIs, binding helpers, directives, styles, and schema
+helpers. The FAST element registry is also available from
+`@microsoft/fast-element/registry.js` for focused definition lookups.
+Declarative, hydration, context, and dependency injection APIs are available
+from their focused path exports.
+
+Focused package path exports remain available for consumers that want to import
+a narrower entrypoint directly. The website's
+[Path Exports](https://www.fast.design/docs/3.x/advanced/path-exports/) page is
+generated from `package.json` and lists each supported path.
+
+## Dynamic Style Application
+
+Import `css`, `CSSTemplateTag`, `CSSValue`, and style APIs such as
+`ElementStyles`, `CSSDirective`, `cssDirective`, `ComposableStyles`,
+`HostBehavior`, `HostController`, `StyleStrategy`, and `StyleTarget` from
+`@microsoft/fast-element`:
+
+```ts
+import { ElementStyles, css } from "@microsoft/fast-element";
+```
+
+When runtime state or external signals need to add or remove styles, create the
+`ElementStyles` with `css` and toggle it through
+`this.$fastController.addStyles()` / `this.$fastController.removeStyles()` from
+the element lifecycle or change handlers.
+
+`css` templates remain static style definitions. Runtime CSS bindings and
+behavior-producing CSS directives are no longer supported; keep the condition on
+the element and toggle a separate `ElementStyles` instance through the
+controller when styles need to change.
+
+## Declarative HTML
+
+FAST Element publishes its declarative HTML runtime from
+`@microsoft/fast-element/declarative.js`. This entrypoint exports the
+functional APIs for declarative templates: `declarativeTemplate()`,
+`TemplateParser`, and related configuration types. `attributeMap()` and
+`observerMap()` are available from their own focused path exports. The
+declarative runtime is pure at import time; declarative APIs lazily install only
+declarative debug messages. Hydration is separate and remains opt-in through
+`enableHydration()` from `@microsoft/fast-element/hydration.js`.
+
+```ts
+import { FASTElement } from "@microsoft/fast-element";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+
+class MyElement extends FASTElement {}
+
+MyElement.define({
+    name: "my-element",
+    template: declarativeTemplate(),
+});
+```
+
+`declarativeTemplate()` automatically defines FAST's internal native
+`<f-template>` publisher in the relevant registry, resolves the matching
+`<f-template name="my-element">`, and keeps the definition template concrete
+before `define()` resolves. If multiple matching `<f-template>` elements are
+connected, the first connected element supplies the template and later duplicates
+do not reassign it. Consumers should not import or define the `<f-template>`
+implementation directly.
+
+Declarative schema behavior is enabled with define extensions:
+
+```ts
+import { attributeMap } from "@microsoft/fast-element/attribute-map.js";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+import { observerMap } from "@microsoft/fast-element/observer-map.js";
+
+MyElement.define(
+    {
+        name: "my-element",
+        template: declarativeTemplate(),
+    },
+    [attributeMap(), observerMap()],
+);
+```
+
+`attributeMap()` creates `@attr`-style accessors for leaf bindings, and
+`observerMap()` creates deep observable accessors for discovered root
+properties. Declarative templates assign `definition.schema` during template
+resolution so these extensions always have schema data when used with
+`declarativeTemplate()`. For non-declarative/manual schema use, import `Schema`
+from `@microsoft/fast-element` and pass it on the element definition;
+`observerMap()` can also receive
+`observerMap({ schema })` directly. When both extensions are present, attribute
+mapping runs before observer mapping.
+
+Declarative utilities such as `deepMerge` are available from
+`@microsoft/fast-element/declarative-utilities.js`. See
+[`DECLARATIVE_HTML.md`](./DECLARATIVE_HTML.md) for declarative implementation
+details and the
+[Declarative HTML docs](https://fast.design/docs/3.x/declarative-templates/overview/)
+for guides on writing f-templates, defining declarative elements, and
+server-side rendering. Declarative event bindings use `$e` for the DOM event
+object and `$c` for the execution context.
+
+## Prerendered Content Optimization
+
+Hydration of prerendered content is **opt-in**. Call `enableHydration()` from `@microsoft/fast-element/hydration.js` before any FAST elements connect to activate the hydration path:
+
+```typescript
+import { enableHydration } from "@microsoft/fast-element/hydration.js";
+
+enableHydration({
+    hydrationComplete() {
+        console.log("hydration complete");
+    },
+});
+```
+
+By default, hydration handles the initial prerendered batch and then no-ops
+after `hydrationComplete` fires. If your app streams Declarative Shadow DOM
+after the initial batch, keep the hydration hook active:
+
+```typescript
+import { enableHydration, StopHydration } from "@microsoft/fast-element/hydration.js";
+
+enableHydration({
+    stopHydration: StopHydration.never,
+});
+```
+
+When hydration is enabled and a FAST element connects with an existing shadow root (from server-side rendering or declarative shadow DOM), `ElementController` detects this and hydrates instead of re-rendering. Two properties on the controller let you inspect the result:
+
+- **`isPrerendered: Promise<boolean>`** — resolves `true` when the element had a declarative shadow root (DSD) at connect time, regardless of whether hydration ran.
+- **`isHydrated: Promise<boolean>`** — resolves `true` only when hydration actually ran successfully.
+
+This enables several optimizations:
+
+- **Hydration instead of re-render**: The template uses `hydrate()` to map existing DOM nodes to binding targets rather than cloning new DOM.
+- **Declarative template resolution**: `declarativeTemplate()` waits for the
+  matching `<f-template>` before `define()` completes, so connected elements
+  hydrate with a concrete template.
+- **Attribute skip**: `onAttributeChangedCallback()` skips processing during initial upgrade when the element is prerendered, since server-rendered attribute values are already correct.
+- **Binding skip**: `HTMLBindingDirective.bind()` skips `updateTarget` for `attribute` and `booleanAttribute` aspect types when the view is prerendered.
+
+### Hydration Mismatch Diagnostics
+
+If a prerendered DOM diverges from the client template in a way FAST cannot
+reconcile (the `render()` empty-boundary and `repeat()` count-mismatch cases
+recover silently), `HydrationBindingError` or `HydrationTargetElementError` is
+thrown. By default the message is a single line pointing at the opt-in
+`hydrationDebugger()`. Install the debugger to get a rich
+"Expected … / Received …" report with the SSR HTML snippet and structured
+`expected` / `received` fields on the thrown error:
+
+```typescript
+import { enableHydration, hydrationDebugger } from "@microsoft/fast-element/hydration.js";
+
+enableHydration({ debugger: hydrationDebugger() });
+```
+
+The debugger module is tree-shaken out of production hydration bundles when
+not imported, so the rich diagnostic helpers only land in builds that opt in.
+
+Per-element lifecycle callbacks can be passed directly to `declarativeTemplate()`:
+
+```typescript
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+
+MyComponent.define({
+    name: "my-component",
+    template: declarativeTemplate({
+        elementWillHydrate(source) {
+            console.log(`${source.localName} will hydrate`);
+        },
+        elementDidHydrate(source) {
+            console.log(`${source.localName} hydrated`);
+        },
+    }),
+});
+```
+
+Component authors can await both promises to distinguish prerendered content from successful hydration:
+
+```typescript
+const controller = this.$fastController;
+const prerendered = await controller.isPrerendered;
+const hydrated = await controller.isHydrated;
+
+if (prerendered && !hydrated) {
+    // Had DSD but hydration wasn't enabled — client-side rendered
+}
+```
+
+Custom directives can also await `controller.isPrerendered` and `controller.isHydrated` (both `Promise<boolean>` on the `ViewController` interface) to determine how the view's content was rendered.
+
+## Define Extensions
+
+The static `define()` method on a `FASTElement` subclass accepts an optional second argument — an array of extension callbacks that are invoked with the resolved element definition before the element is registered with the platform. This enables a plugin pattern where reusable behaviors can hook into element registration.
+
+```typescript
+import { FASTElement, type FASTElementExtension } from "@microsoft/fast-element";
+
+function logger(): FASTElementExtension {
+    return definition => {
+        console.log(`Defining element: ${definition.name}`);
+    };
+}
+
+class MyComponent extends FASTElement {
+    // component code
+}
+
+MyComponent.define({ name: "my-component", template, styles }, [logger()]);
+```
+Each extension receives the full `FASTElementDefinition`, which includes the resolved element name, type, template, styles, and attribute metadata. Extensions run before `customElements.define()`, so any setup they perform is available when existing DOM elements are upgraded.