@lushly-dev/fast-element 0.0.0-stage → 3.0.1-preview.0

package/LICENSE

@@ -0,0 +1,23 @@
+    FAST - https://www.fast.design/
+
+    MIT License
+
+    Copyright (c) Microsoft Corporation. All rights reserved.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

package/README.md

@@ -1,3 +1,281 @@
-# Temporary Holding Version
+# FAST Element
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-element.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-element)
+
+The `fast-element` library is a lightweight means to easily build performant, memory-efficient, standards-compliant Web Components. FAST Elements work in every major browser and can be used in combination with any front-end framework or even without a framework.
+
+## Installation
+
+### From NPM
+
+To install the latest `fast-element` library using `npm`:
+
+```shell
+npm install --save @lushly-dev/fast-element
+```
+
+Within your JavaScript or TypeScript code, you can then import library APIs like this:
+
+```ts
+import { FASTElement } from '@lushly-dev/fast-element';
+```
+
+### From CDN
+
+A pre-bundled script that contains all APIs needed to build web components with FAST Element is available on CDN. You can use this script by adding [`type="module"`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) to the script element and then importing from the CDN.
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <script type="module">
+          import { FASTElement } from "https://cdn.jsdelivr.net/npm/@lushly-dev/fast-element/dist/fast-element.min.js";
+
+          // your code here
+        </script>
+    </head>
+    <!-- ... -->
+</html>
+```
+
+The markup above always references the latest release. When deploying to production, you will want to ship with a specific version. Here's an example of the markup for that:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@lushly-dev/fast-element@1.6.2/dist/fast-element.min.js"></script>
+```
+
+:::note
+For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL.
+:::
+
+:::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 `@lushly-dev/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
+
+`@lushly-dev/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 "@lushly-dev/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/3.x/resources/export-sizes/) documentation page for the latest numbers.
+
+## Root Imports and Path Exports
+
+The root `@lushly-dev/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
+`@lushly-dev/fast-element/registry.js` for focused definition lookups and
+`fastElementRegistry.whenRegistered(tagName)` registration promises.
+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
+`@lushly-dev/fast-element`:
+
+```ts
+import { ElementStyles, css } from "@lushly-dev/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
+`@lushly-dev/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 `@lushly-dev/fast-element/hydration.js`.
+
+```ts
+import { FASTElement } from "@lushly-dev/fast-element";
+import { declarativeTemplate } from "@lushly-dev/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 "@lushly-dev/fast-element/attribute-map.js";
+import { declarativeTemplate } from "@lushly-dev/fast-element/declarative.js";
+import { observerMap } from "@lushly-dev/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 `@lushly-dev/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
+`@lushly-dev/fast-element/declarative-utilities.js`. See
+[`docs/declarative/syntax.md`](./docs/declarative/syntax.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 `@lushly-dev/fast-element/hydration.js` before any FAST elements connect to activate the hydration path:
+
+```typescript
+import { enableHydration } from "@lushly-dev/fast-element/hydration.js";
+
+const hydration = enableHydration();
+
+await hydration.whenHydrated();
+console.log("hydration complete");
+```
+
+By default, hydration handles the initial prerendered batch and then no-ops
+after the active hydration batch completes. If your app streams Declarative
+Shadow DOM after the initial batch, keep the hydration hook active. In this
+mode, `enableHydration().whenHydrated()` intentionally remains pending because
+hydration never reaches a global completion point.
+
+```typescript
+import { enableHydration, StopHydration } from "@lushly-dev/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 "@lushly-dev/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.
+
+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 "@lushly-dev/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.

package/migration/fast-html/rules/README.md

@@ -0,0 +1,15 @@
+# FAST HTML to declarative HTML migration rules
+
+This folder contains `.yml` rules for converting common FAST tagged-template
+patterns to FAST Element v3 declarative HTML using
+[ast-grep](https://ast-grep.github.io/).
+
+Run the rules from the FAST Element package root with:
+
+```bash
+pnpm exec sg scan --config migration/fast-html/sgconfig.yml path/to/source
+```
+
+The generated markup is a migration aid, not a semantic guarantee. Move the
+resulting template into an `.html` file, use `$e` and `$c` for event/context
+arguments, and verify it with the declarative Playwright suite.

package/migration/fast-html/rules/attribute-directives.yml

@@ -0,0 +1,38 @@
+# https://ast-grep.github.io/guide/rule-config.html#rule
+# from: ${ref("defaultSlot")}
+# to: f-ref="{defaultSlot}"
+id: binding - convert attribute directives
+language: typescript
+utils:
+  call-expression:
+    has:
+      nthChild: 1
+      kind: call_expression
+      all:
+        - matches: identifier
+        - matches: arguments
+  identifier:
+    has:
+      nthChild: 1
+      kind: identifier
+      pattern: $DIRECTIVE
+  arguments:
+    has:
+      kind: arguments
+      matches: string
+  string:
+    has:
+      kind: string
+      matches: string-fragment
+  string-fragment:
+    has:
+      kind: string_fragment
+      pattern: $STRING
+constraints:
+  DIRECTIVE:
+    regex: ref|slotted|children
+rule:
+  kind: template_substitution
+  matches: call-expression
+fix:
+  'f-$DIRECTIVE="{$STRING}"'

package/migration/fast-html/rules/call-expression-with-event-argument.yml

@@ -0,0 +1,41 @@
+# https://ast-grep.github.io/guide/rule-config.html#rule
+# from: ${(x, c) => x.foo(c.event)}
+# to: {foo($e)}
+id: binding - convert call expression with event argument
+language: typescript
+utils:
+  arrow-function:
+    has:
+      kind: arrow_function
+      matches: call-expression
+  call-expression:
+    has:
+      kind: call_expression
+      all:
+        - matches: handler-arguments
+        - matches: handler-expression
+  handler-expression:
+    has:
+      kind: member_expression
+      matches: handler-expression-property
+  handler-expression-property:
+    has:
+      kind: property_identifier
+      pattern: $A
+  handler-arguments:
+    has:
+      kind: arguments
+      matches: handler-arguments-member-expression
+  handler-arguments-member-expression:
+    has:
+      kind: member_expression
+      matches: handler-arguments-property-identifier
+  handler-arguments-property-identifier:
+    has:
+      kind: property_identifier
+      pattern: $B
+rule:
+  kind: template_substitution
+  matches: arrow-function
+fix:
+  '{$A($e)}'

package/migration/fast-html/rules/member-expression.yml

@@ -0,0 +1,33 @@
+# https://ast-grep.github.io/guide/rule-config.html#rule
+# from: ${x => x.foo}
+# to: {{foo}}
+id: binding - convert member expression
+language: typescript
+utils:
+  arrow-function:
+    has:
+      kind: arrow_function
+      all:
+        - matches: identifier
+        - matches: member-expression
+  member-expression:
+    has:
+      kind: member_expression
+      nthChild: 2
+      all:
+        - matches: identifier
+        - matches: property-identifier
+  identifier:
+    has:
+      kind: identifier
+      nthChild: 1
+  property-identifier:
+    has:
+      kind: property_identifier
+      nthChild: 2
+      pattern: $A
+rule:
+  kind: template_substitution
+  matches: arrow-function
+fix:
+  '{{$A}}'

package/migration/fast-html/rules/tag-function-to-template-literal.yml

@@ -0,0 +1,16 @@
+# https://ast-grep.github.io/guide/rule-config.html#rule
+# from: export const template = html`<slot></slot>`
+# to: `<slot></slot>`
+id: convert tag function to template literal
+language: typescript
+utils:
+  is-tag-template:
+    has:
+      kind: template_string
+      pattern: $B
+rule:
+  kind: call_expression
+  matches: is-tag-template
+  pattern: $A
+fix:
+  '$B'