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

package/dist/styles/styles.api.json

@@ -1389,7 +1389,7 @@
             },
             {
               "kind": "Content",
-              "text": "<any>;\n    getEvent(): "
+              "text": ";\n    getEvent(): "
             },
             {
               "kind": "Reference",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@microsoft/fast-element",
   "description": "A library for constructing Web Components",
-  "version": "3.0.0-rc.1",
+  "version": "3.0.0-rc.2",
   "author": {
     "name": "Microsoft",
     "url": "https://discord.gg/FcSNfg4"
@@ -35,6 +35,11 @@
       "test": "./src/components/fast-element.ts",
       "default": "./dist/esm/components/fast-element.js"
     },
+    "./registry.js": {
+      "types": "./dist/dts/registry.d.ts",
+      "test": "./src/registry.ts",
+      "default": "./dist/esm/registry.js"
+    },
     "./declarative.js": {
       "types": "./dist/dts/declarative/index.d.ts",
       "test": "./src/declarative/index.ts",
@@ -199,32 +204,39 @@
     "doc": "api-extractor run --local",
     "doc:ci": "api-extractor run",
     "doc:exports": "node ./scripts/run-api-extractor.js",
+    "doc:path-exports": "node ./scripts/check-path-exports-docs.js --write",
+    "doc:path-exports:check": "node ./scripts/check-path-exports-docs.js --check",
     "doc:exports:ci": "node ./scripts/run-api-extractor.js ci",
-    "build": "npm run build:tsc && npm run build:rollup && npm run build:sizes && npm run doc && npm run doc:exports && npm run build:fixtures",
+    "build": "npm run build:tsc && npm run test:exports && npm run build:rollup && npm run build:sizes && npm run doc && npm run doc:exports && npm run build:fixtures",
     "build:fixtures": "node scripts/declarative/build-fixtures.js",
     "build:fixtures:webui": "node scripts/declarative/build-fixtures-with-webui.js",
     "build:rollup": "rollup -c",
     "build:sizes": "node scripts/measure-sizes.js",
-    "build:tsc": "tsc -p ./tsconfig.json",
-    "dev": "tsc -p ./tsconfig.json -w",
+    "build:tsc": "tsgo -p ./tsconfig.json",
+    "dev": "tsgo -p ./tsconfig.json -w",
     "dev:declarative": "concurrently -k -n tsc,server \"npm run dev\" \"npm run test-server:declarative\"",
     "prepublishOnly": "npm run clean && npm run build",
     "lint": "biome-changed",
     "lint:fix": "biome-changed -- --fix",
     "test:playwright": "playwright test && npm run test:playwright:declarative",
+    "test:exports": "node ./scripts/smoke-package-exports.js",
     "test:playwright:declarative": "playwright test --config=playwright.declarative.config.ts",
     "test:chromium": "playwright test --project=chromium && npm run test:chromium:declarative",
     "test:chromium:declarative": "playwright test --config=playwright.declarative.config.ts --project=chromium",
     "test-server": "npx vite test/ --clearScreen false",
     "test-server:declarative": "npx vite test/declarative --clearScreen false --port 5174 --strictPort",
     "test-server:declarative:webui": "npx vite temp/integrations/webui --clearScreen false --port 5174 --strictPort",
-    "test": "npm run lint && npm run doc:ci && npm run doc:exports:ci && npm run test:playwright",
-    "test:ci": "npm run doc:ci && npm run doc:exports:ci && npm run test:playwright",
+    "test": "npm run lint && npm run doc:path-exports:check && npm run doc:ci && npm run doc:exports:ci && npm run test:exports && npm run test:playwright",
+    "test:ci": "npm run doc:path-exports:check && npm run doc:ci && npm run doc:exports:ci && npm run test:exports && npm run test:playwright",
     "test:ui:declarative": "concurrently -k -n tsc,playwright \"npm run dev\" \"npx playwright test --config=playwright.declarative.config.ts --ui\"",
     "test:webui-integration": "npm run build:fixtures:webui && playwright test --config=playwright.declarative.webui.config.ts"
   },
   "devDependencies": {
-    "@microsoft/fast-build": "*",
-    "@microsoft/webui": "0.0.10"
-  }
+    "@microsoft/fast-build": "0.8.0-fast-element-v3-rc-20260615",
+    "@microsoft/webui": "0.0.12"
+  },
+  "files": [
+    "./dist",
+    "CHANGELOG.md"
+  ]
 }

package/ARCHITECTURE_FASTELEMENT.md

@@ -1,63 +0,0 @@
-# FASTElement
-
-The `FASTElement` is our extension of the `HTMLElement`. As such it leverages the lifecycles but also requires additional setup before before the class `constructor` or the `connectedCallback` method is executed which are explained in the [overview](./ARCHITECTURE_OVERVIEW.md). This document explains specifically what `FASTElement` leverages inside the `HTMLElement`s lifecycle hooks.
-
-For an explanation into `HTMLElement` lifecycle hooks refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks).
-
-## A Custom Element is Detected by the Browser
-
-Because the `FASTElement` is an extension of the `HTMLElement`, it makes use of the same lifecycle hooks and extends them with `$fastController`. It also initializes using another class `ElementController`, the methods this are called during the custom elements native `constructor`, `connectedCallback`, `disconnectedCallback`, and `attributeChangedCallback` lifecycle hooks.
-
-### 🔄 **Lifecycle**: Initialization
-
-```mermaid
-flowchart TD
-    A[A <code>FASTElement</code> web component is added to the <code>DOM</code>] --> B
-    B[<code>FASTElement</code> initializes the <code>ElementController.forCustomElement</code> passing the Custom Element instance] --> C
-    B --> F[Observables applied to the <code>FASTElement</code> are updated on the FAST global without values]
-    C{Is an <code>ElementController</code> available?}
-    C --> |yes|E
-    C --> |no|D
-    D[Initialize a new <code>ElementController</code> referred to as setting an element controller strategy]
-    D --> F
-    E[<code>ElementController</code> captures the Custom Element instance and the definition and attaches them to the <code>$fastController</code> which is then attached to the instance]
-```
-
-### 🔄 **Lifecycle**: Component is connected
-
-```mermaid
-flowchart TD
-    A[browser <code>HTMLElement</code>'s <code>connectedCallback</code> is called] --> B
-    B[<code>this.$fastController.connect</code> in FASTElement is called] --> C
-    B --> D
-    B --> E
-    B --> F
-    C[bind observables by capturing the Custom Elements properties and setting the values from the bound observables on the Custom Element]
-    D[connect behaviors by call the <code>connectedCallback</code> on all behaviors]
-    E[render template, execute an <code>ElementViewTemplate</code>'s render method]
-    F[add styles either as an appended <code>StyleElement</code> node or an <code>adoptedStylesheet</code> which may include and attach behaviors]
-```
-
-#### Render Template
-
-The rendering of the template on the `ElementController` is by the `renderTemplate` method which is called during the `ElementController.connect` method which is triggered by `HTMLElement`s `connectedCallback` lifecycle.
-
-The `renderTemplate` identifies the Custom Element, and the shadow root associated with the Custom Element. This then places a rendering of the template (an `ElementView`) onto the internal `view` of the controller. When creating the `ElementView`/`HTMLView` using the `ViewTemplate.render`, the `Compiler.compile()` method identifies a `DocumentFragment` either by using an existing `<template>` tag, or creating one to wrap the contents of the shadow root. A new `CompilationContext` is created and the `compileAttributes` function is called, this results in the replacement of the placeholder attributes initally set-up during the pre-render step with their values if a value has been assigned. The factories with the associated nodes identified are then passed to the context. The view then binds all behaviors to the source element. The `CompilationContext.createView` is executed with the `DocumentFragment` as the root, and returns an `HTMLView`. This `HTMLView` includes an `appendTo` method to attach the fragment to the host element, which it then does. It should be noted that the compiled HTML is a `string`, which when set on the `DocumentFragment` as `innerHTML`, this allows the browser to dictate the creation of HTML nodes.
-
-### 🔄 **Lifecycle**: Component is disconnected
-
-When a component is disconnected, a cleanup step is created to remove associated behaviors.
-
-### 🔄 **Lifecycle**: Attribute has been changed
-
-Attributes have an `AttributeDefinition` which allows for converters, attachment of the `<attributName>Changed` aspect of the `@attr` decorator among other capabilities.
-
-```mermaid
-flowchart TD
-    A[The browser <code>HTMLElement</code>'s <code>attributeChangedCallback</code> is called] --> B
-    B[<code>this.$fastController.onAttributeChangedCallback</code> in <code>FASTElement</code> is called] --> C
-    C[calls the attribute definitions <code>onAttributeChangedCallback</code> method with the updated value] --> D
-    D[An <code>Updates.enqueue</code> is called which places the update in the task queue which is then executed, these are performed async unless otherwise specified]
-```
-
-These changes are observed and similar to the way `Observables` work, they utilize an `Accessor` pattern which has a `getValue` and `setValue` in which DOM updates are applied.

package/ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md

@@ -1,36 +0,0 @@
-# `html` tagged template literal
-
-The `html` export from `@microsoft/fast-element` is used to create the template logic for the custom element.
-
-## Pre-processing the `html` tagged template literal contents
-
-Before the template can be used it goes through a step to convert it into a `ViewTemplate` which it does via the `ViewTemplate.create()` method. This is then used during the `compose` step, before `FASTElement` is instantiated.
-
-During the static `ViewTemplate.create()` method (called by the `html` tag), the following happens for each string:
-- Factories with unique IDs are created for each tag template literal argument (or `TemplateValue`) which matches with the corresponding string
-- A binding is created from the `TemplateValue`
-
-The `Compiler.compile()` method is called lazily the first time the template is rendered (via `ViewTemplate.compile()`, which is triggered by `ViewTemplate.create()` instance method or `ViewTemplate.render()`).
-
-A resulting string using a `createHTML()` function is produced using the `HTMLDirective`s executed for each factory. The behavior is augmented by the previous string from the `html` tag template which determines the aspect if one exists, these aspects are the `@`, `:`, or other binding aspect attached to attributes.
-
-The `createHTML()` function utilizes a `Markup` attribute which is assigned to a factory's unique ID. The strings are concatenated and passed to a new `ViewTemplate` with all the factories (empty until one is assigned) that act as a dictionary with the unique IDs as the key to look up each factory once it has been created. The string this creates is injected into a `<template>` as `innerHTML`, which allows the browser to create the nodes and placeholder factory IDs, with the only `DOM` node that is explicitly created being the wrapping `<template>` element.
-
-## Directives
-
-The `HTMLBindingDirective` applies bindings to items identified as various `TemplateValue`s within the `html` tagged template. The `createHTML` step uses the factory associated with the binding to create strings in the markup using the factory's ID.
-
-```mermaid
-flowchart TD
-    A[A <code>new HTMLBindingDirective</code> is created with a data binding which has a policy, options, <code>createObserver</code>, and an evaluate method assigned to the passed arrow function such as <pre>x => x.foo</pre>]
-    B[<code>oneTime</code> binding passes the corresponding tag template argument, an arrow function]
-    C[<code>oneWay</code> binding passes a copy of the corresponding tag template argument, an arrow function]
-    D[An already specified binding such as a <code>repeat</code> or <code>when</code> directive is passed]
-    A --> B
-    A --> C
-    A --> D
-    E[When a <code>createObserver</code> is called, an <code>Observable.binding</code> is created passing the arrow function to be evaluated and the subscriber to be notified]
-    C --> E
-    F[When a <code>createObserver</code> is called, the instance of the one time binding is returned which includes a bind method returning the arrow function executed against the controller source and context]
-    B --> F
-```

package/ARCHITECTURE_INTRO.md

@@ -1,10 +0,0 @@
-# Introduction
-
-This document (and the linked documents) explains how the exports and side effects of `@microsoft/fast-element` are used to create custom elements.
-
-## Glossary
-
-- [Overview](./ARCHITECTURE_OVERVIEW.md): How the `@microsoft/fast-element` should be used by a developer and what code is executed during the first render.
-- [`FASTElement`](./ARCHITECTURE_FASTELEMENT.md): How the `FASTElement` is architected.
-- [`html` tagged template literal](./ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md): How the `html` tagged template literal takes and converts the contents into a `ViewTemplate`.
-- [`Updates` queue](./ARCHITECTURE_UPDATES.md): How updates to attributes and observables are processed.

package/ARCHITECTURE_OVERVIEW.md

@@ -1,52 +0,0 @@
-# General FAST usage
-
-`FASTElement` is an extension of `HTMLElement` which makes use of Custom Element APIs native to the browser. It also supplies the following methods:
-
-- The `compose` method combines the Custom Element name, template, style, and other options to create the definition for the Custom Element.
-- The `define` method makes use of the native Custom Element [`define()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define) to register the Custom Element with a Custom Element Registry.
-- The `from` method allows the use of Customized Built-in elements, which extend from native elements such as `HTMLButtonElement`.
-
-### Creating a Custom Element from FASTElement
-
-A basic developer flow for defining a custom element looks like this:
-
-```mermaid
-flowchart TD
-    A[Create a <code>FASTElement</code> web component by extending the <code>FASTElement</code> class] --> F
-    F[Compose with <code>FASTElement.compose</code> to include template and styles] --> G[Define the component in the browser with <code>FASTElement.define</code>]
-```
-
-Let's take a look at the compose step to see what the FAST architecture is doing at this stage.
-
-### Composing a Custom Element
-
-The `FASTElement.compose()` function creates a new `FASTElementDefinition`, which includes all metadata needed for the element (such as templates, attributes, and styles). The element definition is registered with the global `FAST` for re-use, and the `FASTElementDefinition` is returned. The resulting object can be retrieved via `ElementController.definition`.
-
-## A Custom Element in JavaScript is sent to the Browser
-
-Let's step back from defining the Custom Element and consider what is happening when we import from the `@microsoft/fast-element` package.
-
-First, a global `FAST` property will be created if one does not already exist, typically in browser on the `window`.
-
-Additionally, when Custom Elements are included in a script a few things might happen even before a Custom Element gets detected by the browser. First, there are initial side effects caused by the use of decorators. These include the `attr` decorator from `@microsoft/fast-element` and the `observable` decorator from `@microsoft/fast-element`.
-
-Here is a basic flow of what code is executed and when during initial load of a script that contains a FAST defined Custom Element:
-
-```mermaid
-flowchart TD
-    A@{ shape: circle, label: "The browser loads the JavaScript file containing FAST and FAST Custom Element definitions" }
-    B@{ shape: rect, label: "The FAST global is added to the window" }
-    A --> B
-    C@{ shape: rect, label: "A Custom Element executes the <code>compose</code> step"}
-    B --> C
-    D@{ shape: procs, label: "<ul style='text-align: left'><li>Any defined observable decorators are added to the FAST global</li><li>An attribute decorator locates the associated Custom Elements constructor which it uses to push itself to the Custom Elements attribute collection</li></ul>"}
-    C --> D
-    F@{ shape: rect, label: "An HTML tagged template literal is executed for the FAST Custom Element and applied to the definition" }
-    D --> F
-    G@{ shape: rect, label: "The <code>define</code> step is hit and the <code>customElement</code> is registered with the Custom Element Registry" }
-    F --> G
-    H@{ shape: rect, label: "A Custom Element is detected on the page and the browser initializes it" }
-    I@{ shape: dbl-circ, label: "The lifecycle steps for <code>FASTElement</code> are executed" }
-    G --> H
-    H --> I
-```

package/ARCHITECTURE_UPDATES.md

@@ -1,11 +0,0 @@
-# `Updates`
-
-The `Updates` API is part of the `FAST` global. The updates that are queued include updates to attributes, observables, and observed arrays.
-
-## Attributes
-
-An attribute change may be queued when the value of the attribute is updated. This change is triggered by `HTMLElement` lifecycle hook `attributeChangedCallback`. The `Updates` queue is used to try to reflect the attribute with the updated value onto the element using `DOM` APIs.
-
-## Observables
-
-The `Reflect` API is used to override `defineProperty` in order to observe a property on an Custom Element, this overrides the getter and setter, which allows subscribers to be notified of changes. Any changes which `set` the value are passed to the `Updates` queue.