@microsoft/fast-element 2.0.0-beta.20 → 2.0.0-beta.21

package/CHANGELOG.json

@@ -1,6 +1,27 @@
 {
   "name": "@microsoft/fast-element",
   "entries": [
+    {
+      "date": "Tue, 14 Feb 2023 04:02:35 GMT",
+      "tag": "@microsoft/fast-element_v2.0.0-beta.21",
+      "version": "2.0.0-beta.21",
+      "comments": {
+        "prerelease": [
+          {
+            "author": "rob@bluespire.com",
+            "package": "@microsoft/fast-element",
+            "commit": "d38d31d2dd7496b5eb1e7c65b57de9a5e05e8546",
+            "comment": "fix: cleanup types, docs, etc. in root source files of fast-element in preparation for release"
+          },
+          {
+            "author": "nicholasrice@users.noreply.github.com",
+            "package": "@microsoft/fast-element",
+            "commit": "09d57ca18700331d054515c3b3f6fae07528cca0",
+            "comment": "Remove un-necessary expression from StyleElementStrategy"
+          }
+        ]
+      }
+    },
     {
       "date": "Wed, 11 Jan 2023 22:07:47 GMT",
       "tag": "@microsoft/fast-element_v2.0.0-beta.20",

package/CHANGELOG.md

@@ -1,9 +1,18 @@
 # Change Log - @microsoft/fast-element
 
-This log was last generated on Wed, 11 Jan 2023 22:07:47 GMT and should not be manually modified.
+This log was last generated on Tue, 14 Feb 2023 04:02:35 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## 2.0.0-beta.21
+
+Tue, 14 Feb 2023 04:02:35 GMT
+
+### Changes
+
+- fix: cleanup types, docs, etc. in root source files of fast-element in preparation for release (rob@bluespire.com)
+- Remove un-necessary expression from StyleElementStrategy (nicholasrice@users.noreply.github.com)
+
 ## 2.0.0-beta.20
 
 Wed, 11 Jan 2023 22:07:47 GMT

package/dist/dts/context.d.ts

@@ -11,31 +11,31 @@ export declare type Context<T> = {
  * A constant key that can be used to represent a Context dependency.
  * The key can be used for context or DI but also doubles as a decorator for
  * resolving the associated dependency.
- * @beta
+ * @public
  */
 export declare type ContextDecorator<T = any> = Readonly<Context<T>> & PropertyDecorator & ParameterDecorator;
 /**
  * A Context object defines an optional initial value for a Context, as well as a name identifier for debugging purposes.
  * The FASTContext can also be used as a decorator to declare context dependencies or as a key for DI.
- * @beta
+ * @public
  */
 export declare type FASTContext<T> = ContextDecorator<T> & {
     get(target: EventTarget): T;
     provide(target: EventTarget, value: T): void;
     request(target: EventTarget, callback: ContextCallback<T>, multiple?: boolean): void;
-    handle(target: EventTarget, callback: (event: ContextEvent<FASTContext<T>>) => void): any;
+    handle(target: EventTarget, callback: (event: ContextEvent<FASTContext<T>>) => void): void;
 };
 /**
  * A strategy that controls how all Context.request API calls are handled.
  * @remarks
- * By default this is handled via Context.dispatch, which dispatched a ContextEvent.
- * @beta
+ * By default this is handled via Context.dispatch, which dispatches a ContextEvent.
+ * @public
  */
 export declare type FASTContextRequestStrategy = <T extends UnknownContext>(target: EventTarget, context: T, callback: ContextCallback<ContextType<T>>, multiple: any) => void;
 declare const contextEventType = "context-request";
 /**
  * Enables using the {@link https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md | W3C Community Context protocol.}
- * @beta
+ * @public
  */
 export declare const Context: Readonly<{
     /**

package/dist/dts/dom-policy.d.ts

@@ -2,10 +2,12 @@ import { DOMAspect, DOMPolicy, DOMSink } from "./dom.js";
 import { TrustedTypesPolicy } from "./interfaces.js";
 /**
  * A specific DOM sink guard for a node aspect.
+ * @public
  */
 export declare type DOMSinkGuards = Record<string, (tagName: string | null, aspect: DOMAspect, aspectName: string, sink: DOMSink) => DOMSink>;
 /**
  * Aspect-specific guards for a DOM Policy.
+ * @public
  */
 export declare type DOMAspectGuards = {
     /**
@@ -35,17 +37,26 @@ export declare type DOMAspectGuards = {
 };
 /**
  * Element-specific guards for a DOM Policy.
+ * @public
  */
 export declare type DOMElementGuards = Record<string, DOMAspectGuards>;
 /**
  * Guard configuration for a DOM Policy.
+ * @public
  */
 export declare type DOMGuards = {
+    /**
+     * Guards for specific elements.
+     */
     elements: DOMElementGuards;
+    /**
+     * General aspect guards independent of the element type.
+     */
     aspects: DOMAspectGuards;
 };
 /**
  * Options for creating a DOM Policy.
+ * @public
  */
 export declare type DOMPolicyOptions = {
     /**
@@ -57,6 +68,10 @@ export declare type DOMPolicyOptions = {
      */
     guards?: Partial<DOMGuards>;
 };
+/**
+ * A helper for creating DOM policies.
+ * @public
+ */
 declare const DOMPolicy: Readonly<{
     /**
      * Creates a new DOM Policy object.

package/dist/dts/interfaces.d.ts

@@ -53,7 +53,7 @@ export declare type Mutable<T> = {
 };
 /**
  * The FAST global.
- * @internal
+ * @public
  */
 export interface FASTGlobal {
     /**
@@ -114,6 +114,7 @@ export declare const enum Message {
     directCallToHTMLTagNotAllowed = 1206,
     onlySetTemplatePolicyOnce = 1207,
     cannotSetTemplatePolicyAfterCompilation = 1208,
+    blockedByDOMPolicy = 1209,
     missingElementDefinition = 1401,
     noRegistrationForContext = 1501,
     noFactoryForResolver = 1502,

package/dist/dts/metadata.d.ts

@@ -8,18 +8,18 @@ export declare const Metadata: Readonly<{
      * @param Type - The type to get the metadata for.
      * @returns The metadata array or a frozen empty array if no metadata is found.
      */
-    getDesignParamTypes: (Type: any) => any;
+    getDesignParamTypes: (Type: Constructable) => readonly any[];
     /**
      * Gets the "annotation:paramtypes" metadata for the specified type.
      * @param Type - The type to get the metadata for.
      * @returns The metadata array or a frozen empty array if no metadata is found.
      */
-    getAnnotationParamTypes: (Type: any) => any;
+    getAnnotationParamTypes: (Type: Constructable) => readonly any[];
     /**
-     *
-     * @param Type - Gets the "annotation:paramtypes" metadata for the specified type. If none is found,
+     * Gets the "annotation:paramtypes" metadata for the specified type. If none is found,
      * an empty, mutable metadata array is created and added.
-     * @returns The metadata array.
+     * @param Type - The type to get or create the metadata for.
+     * @returns A mutable metadata array.
      */
     getOrCreateAnnotationParamTypes(Type: Constructable): any[];
 }>;

package/dist/dts/pending-task.d.ts

@@ -1,20 +1,32 @@
-/**
- * This module provides
- */
 /**
  * An implementation of the https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/pending-task.md proposal.
- * @beta
+ * @public
  */
 export interface PendingTask extends Event {
-    complete: Promise<void>;
+    /**
+     * A promise that resolves when the pending task is complete.
+     */
+    readonly complete: Promise<void>;
 }
 /**
  * A concrete implementation of {@link PendingTask}
- * @beta
+ * @public
  */
 export declare class PendingTaskEvent extends Event implements PendingTask {
-    complete: Promise<void>;
+    readonly complete: Promise<void>;
+    /**
+     * The type of the pending task event.
+     */
     static readonly type = "pending-task";
+    /**
+     * Creates an instance of PendingTaskEvent.
+     * @param complete - A promise that resolves when the pending task is complete.
+     */
     constructor(complete: Promise<void>);
+    /**
+     * Determines whether a value is a PendingTaskEvent.
+     * @param value - The value to check.
+     * @returns True if the value is a PendingTaskEvent; false otherwise.
+     */
     static isPendingTask<T extends Event>(value: T | PendingTask): value is PendingTask;
 }

package/dist/dts/platform.d.ts

@@ -2,7 +2,7 @@ import type { FASTGlobal } from "./interfaces.js";
 import "./polyfills.js";
 /**
  * The FAST global.
- * @internal
+ * @public
  */
 export declare const FAST: FASTGlobal;
 /**

package/dist/dts/utilities.d.ts

@@ -14,7 +14,7 @@ export declare function composedParent<T extends HTMLElement>(element: T): HTMLE
  * Determines if the reference element contains the test element in a "composed" DOM tree that
  * ignores shadow DOM boundaries.
  *
- * Returns true of the test element is a descendent of the reference, or exist in
+ * Returns true of the test element is a descendent of the reference, or exists in
  * a shadow DOM that is a logical descendent of the reference. Otherwise returns false.
  * @param reference - The element to test for containment against.
  * @param test - The element being tested for containment.
@@ -23,13 +23,14 @@ export declare function composedParent<T extends HTMLElement>(element: T): HTMLE
  */
 export declare function composedContains(reference: HTMLElement, test: HTMLElement): boolean;
 /**
+ * An extension of MutationObserver that supports unobserving nodes.
  * @internal
  */
 export declare class UnobservableMutationObserver extends MutationObserver {
     private readonly callback;
     private observedNodes;
     /**
-     * An extension of MutationObserver that supports unobserving nodes.
+     * Creates an instance of UnobservableMutationObserver.
      * @param callback - The callback to invoke when observed nodes are changed.
      */
     constructor(callback: MutationCallback);

package/dist/esm/components/element-controller.js

@@ -478,7 +478,6 @@ export class StyleElementStrategy {
     removeStylesFrom(target) {
         target = usableStyleTarget(normalizeStyleTarget(target));
         const styles = target.querySelectorAll(`.${this.styleClass}`);
-        styles[0].parentNode;
         for (let i = 0, ii = styles.length; i < ii; ++i) {
             target.removeChild(styles[i]);
         }

package/dist/esm/context.js

@@ -5,7 +5,7 @@ const contextEventType = "context-request";
 let requestStrategy;
 /**
  * Enables using the {@link https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md | W3C Community Context protocol.}
- * @beta
+ * @public
  */
 export const Context = Object.freeze({
     /**
@@ -132,7 +132,7 @@ export const Context = Object.freeze({
      * initialValue if the context isn't handled.
      */
     defineProperty(target, propertyName, context) {
-        const field = `$di_${propertyName}`;
+        const field = Symbol.for(`fast:di:${propertyName}`);
         Reflect.defineProperty(target, propertyName, {
             get: function () {
                 var _a;

package/dist/esm/debug.js

@@ -17,6 +17,7 @@ const debugMessages = {
     [1206 /* directCallToHTMLTagNotAllowed */]: "Calling html`` as a normal function invalidates the security guarantees provided by FAST.",
     [1207 /* onlySetTemplatePolicyOnce */]: "The DOM Policy for an HTML template can only be set once.",
     [1208 /* cannotSetTemplatePolicyAfterCompilation */]: "The DOM Policy cannot be set after a template is compiled.",
+    [1209 /* blockedByDOMPolicy */]: "'${aspectName}' on '${tagName}' is blocked by the current DOMPolicy.",
     [1401 /* missingElementDefinition */]: "Missing FASTElement definition.",
     [1501 /* noRegistrationForContext */]: "No registration for Context/Interface '${name}'.",
     [1502 /* noFactoryForResolver */]: "Dependency injection resolver for '${key}' returned a null factory.",

package/dist/esm/di/di.js

@@ -371,16 +371,16 @@ export const DI = Object.freeze({
      * The respectConnection option is only applicable to elements that descend from FASTElement.
      */
     defineProperty(target, propertyName, key, respectConnection = false) {
-        const diPropertyKey = `$di_${propertyName}`;
+        const field = Symbol.for(`fast:di:${propertyName}`);
         Reflect.defineProperty(target, propertyName, {
             get: function () {
-                let value = this[diPropertyKey];
+                let value = this[field];
                 if (value === void 0) {
                     const container = this instanceof Node
                         ? DI.findResponsibleContainer(this)
                         : DI.getOrCreateDOMContainer();
                     value = container.get(key);
-                    this[diPropertyKey] = value;
+                    this[field] = value;
                     if (respectConnection) {
                         const notifier = this.$fastController;
                         if (!notifier) {
@@ -389,9 +389,9 @@ export const DI = Object.freeze({
                         const handleChange = () => {
                             const newContainer = DI.findResponsibleContainer(this);
                             const newValue = newContainer.get(key);
-                            const oldValue = this[diPropertyKey];
+                            const oldValue = this[field];
                             if (newValue !== oldValue) {
-                                this[diPropertyKey] = value;
+                                this[field] = value;
                                 notifier.notify(propertyName);
                             }
                         };

package/dist/esm/dom-policy.js

@@ -1,5 +1,6 @@
 import { DOMAspect } from "./dom.js";
 import { isString } from "./interfaces.js";
+import { FAST } from "./platform.js";
 function safeURL(tagName, aspect, aspectName, sink) {
     return (target, name, value, ...rest) => {
         if (isString(value)) {
@@ -9,7 +10,10 @@ function safeURL(tagName, aspect, aspectName, sink) {
     };
 }
 function block(tagName, aspect, aspectName, sink) {
-    throw new Error(`${aspectName} on ${tagName !== null && tagName !== void 0 ? tagName : "text"} is blocked by the current DOMPolicy.`);
+    throw FAST.error(1209 /* Message.blockedByDOMPolicy */, {
+        aspectName,
+        tagName: tagName !== null && tagName !== void 0 ? tagName : "text",
+    });
 }
 const defaultDOMElementGuards = {
     a: {
@@ -303,6 +307,10 @@ function tryGuard(aspectGuards, tagName, aspect, aspectName, sink) {
         }
     }
 }
+/**
+ * A helper for creating DOM policies.
+ * @public
+ */
 const DOMPolicy = Object.freeze({
     /**
      * Creates a new DOM Policy object.

package/dist/esm/metadata.js

@@ -22,6 +22,7 @@ if (!("metadata" in Reflect)) {
         return void 0;
     };
 }
+const annotationParamTypesKey = "annotation:paramtypes";
 /**
  * Provides basic metadata capabilities used by Context and Dependency Injection.
  */
@@ -31,29 +32,29 @@ export const Metadata = Object.freeze({
      * @param Type - The type to get the metadata for.
      * @returns The metadata array or a frozen empty array if no metadata is found.
      */
-    getDesignParamTypes: Type => {
+    getDesignParamTypes: (Type) => {
         var _a;
-        return (_a = Reflect.getOwnMetadata("design:paramtypes", Type)) !== null && _a !== void 0 ? _a : emptyArray;
+        return ((_a = Reflect.getOwnMetadata("design:paramtypes", Type)) !== null && _a !== void 0 ? _a : emptyArray);
     },
     /**
      * Gets the "annotation:paramtypes" metadata for the specified type.
      * @param Type - The type to get the metadata for.
      * @returns The metadata array or a frozen empty array if no metadata is found.
      */
-    getAnnotationParamTypes: Type => {
+    getAnnotationParamTypes: (Type) => {
         var _a;
-        return (_a = Reflect.getOwnMetadata("annotation:paramtypes", Type)) !== null && _a !== void 0 ? _a : emptyArray;
+        return ((_a = Reflect.getOwnMetadata(annotationParamTypesKey, Type)) !== null && _a !== void 0 ? _a : emptyArray);
     },
     /**
-     *
-     * @param Type - Gets the "annotation:paramtypes" metadata for the specified type. If none is found,
+     * Gets the "annotation:paramtypes" metadata for the specified type. If none is found,
      * an empty, mutable metadata array is created and added.
-     * @returns The metadata array.
+     * @param Type - The type to get or create the metadata for.
+     * @returns A mutable metadata array.
      */
     getOrCreateAnnotationParamTypes(Type) {
         let types = this.getAnnotationParamTypes(Type);
         if (types === emptyArray) {
-            Reflect.defineMetadata("annotation:paramtypes", (types = []), Type);
+            Reflect.defineMetadata(annotationParamTypesKey, (types = []), Type);
         }
         return types;
     },

package/dist/esm/pending-task.js

@@ -1,16 +1,28 @@
 /**
  * A concrete implementation of {@link PendingTask}
- * @beta
+ * @public
  */
 export class PendingTaskEvent extends Event {
+    /**
+     * Creates an instance of PendingTaskEvent.
+     * @param complete - A promise that resolves when the pending task is complete.
+     */
     constructor(complete) {
         super(PendingTaskEvent.type, { bubbles: true, composed: true });
         this.complete = complete;
     }
+    /**
+     * Determines whether a value is a PendingTaskEvent.
+     * @param value - The value to check.
+     * @returns True if the value is a PendingTaskEvent; false otherwise.
+     */
     static isPendingTask(value) {
         var _a;
         return (value.type === PendingTaskEvent.type &&
             typeof ((_a = value.complete) === null || _a === void 0 ? void 0 : _a.then) === "function");
     }
 }
+/**
+ * The type of the pending task event.
+ */
 PendingTaskEvent.type = "pending-task";

package/dist/esm/platform.js

@@ -10,7 +10,7 @@ if (globalThis.FAST === void 0) {
 }
 /**
  * The FAST global.
- * @internal
+ * @public
  */
 export const FAST = globalThis.FAST;
 if (FAST.getById === void 0) {

package/dist/esm/utilities.js

@@ -28,7 +28,7 @@ export function composedParent(element) {
  * Determines if the reference element contains the test element in a "composed" DOM tree that
  * ignores shadow DOM boundaries.
  *
- * Returns true of the test element is a descendent of the reference, or exist in
+ * Returns true of the test element is a descendent of the reference, or exists in
  * a shadow DOM that is a logical descendent of the reference. Otherwise returns false.
  * @param reference - The element to test for containment against.
  * @param test - The element being tested for containment.
@@ -46,11 +46,12 @@ export function composedContains(reference, test) {
     return false;
 }
 /**
+ * An extension of MutationObserver that supports unobserving nodes.
  * @internal
  */
 export class UnobservableMutationObserver extends MutationObserver {
     /**
-     * An extension of MutationObserver that supports unobserving nodes.
+     * Creates an instance of UnobservableMutationObserver.
      * @param callback - The callback to invoke when observed nodes are changed.
      */
     constructor(callback) {