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

package/dist/fast-element.d.ts

@@ -321,6 +321,17 @@ export declare class ChildrenDirective extends NodeObservationDirective<Children
  */
 export declare type ChildrenDirectiveOptions<T = any> = ChildListDirectiveOptions<T> | SubtreeDirectiveOptions<T>;
 
+/**
+ * Represents a constructable class with a prototype.
+ * @public
+ */
+export declare type Class<T, C = {}> = C & Constructable<T> & {
+    /**
+     * The class's prototype;
+     */
+    readonly prototype: T;
+};
+
 /**
  * A function capable of compiling a template from the preprocessed form produced
  * by the html template function into a result that can instantiate views.
@@ -391,7 +402,7 @@ declare function compose<TType extends Constructable<HTMLElement> = Constructabl
 declare function compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): FASTElementDefinition<TType>;
 
 /**
- * Allows for the creation of Constructable mixin classes.
+ * Represents a type which can be constructed with the new operator.
  *
  * @public
  */
@@ -517,12 +528,6 @@ export declare interface CSSDirectiveDefinition<TType extends Constructable<CSSD
     readonly type: TType;
 }
 
-/**
- * @deprecated Use css.partial instead.
- * @public
- */
-export declare const cssPartial: (strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]) => CSSDirective;
-
 /**
  * Transforms a template literal string into styles.
  * @param strings - The string fragments that are interpolated with the values.
@@ -550,24 +555,6 @@ export declare type CSSTemplateTag = ((strings: TemplateStringsArray, ...values:
  */
 export declare function customElement(nameOrDef: string | PartialFASTElementDefinition): (type: Constructable<HTMLElement>) => void;
 
-/**
- * Injects static HTML without platform protection.
- * @param html - The html to injection.
- * @returns A DangerousHTMLDirective.
- * @public
- */
-export declare function dangerousHTML<TSource = any, TParent = any>(html: string): CaptureType<TSource, TParent>;
-
-/**
- * A directive capable of injecting static HTML platform runtime protection.
- * @public
- */
-export declare class DangerousHTMLDirective implements HTMLDirective {
-    private html;
-    constructor(html: string);
-    createHTML(): string;
-}
-
 /**
  * Metadata used to configure a custom attribute's behavior through a decorator.
  * @public
@@ -594,21 +581,6 @@ export declare interface Disposable {
  * @public
  */
 export declare const DOM: Readonly<{
-    /**
-     * @deprecated
-     * Use Updates.enqueue().
-     */
-    queueUpdate: (callable: Callable) => void;
-    /**
-     * @deprecated
-     * Use Updates.next()
-     */
-    nextUpdate: () => Promise<void>;
-    /**
-     * @deprecated
-     * Use Updates.process()
-     */
-    processUpdates: () => void;
     /**
      * Gets the dom policy used by the templating system.
      */
@@ -1325,7 +1297,7 @@ export declare interface HostController<TSource = any> {
  * other template instances, and Directive instances.
  * @public
  */
-export declare function html<TSource = any, TParent = any>(strings: TemplateStringsArray, ...values: TemplateValue<TSource, TParent>[]): ViewTemplate<TSource, TParent>;
+export declare const html: HTMLTemplateTag;
 
 /**
  * A directive that applies bindings.
@@ -1456,6 +1428,24 @@ export declare interface HTMLTemplateCompilationResult<TSource = any, TParent =
     createView(hostBindingTarget?: Element): HTMLView<TSource, TParent>;
 }
 
+/**
+ * Transforms a template literal string into a ViewTemplate.
+ * @param strings - The string fragments that are interpolated with the values.
+ * @param values - The values that are interpolated with the string fragments.
+ * @remarks
+ * The html helper supports interpolation of strings, numbers, binding expressions,
+ * other template instances, and Directive instances.
+ * @public
+ */
+export declare type HTMLTemplateTag = (<TSource = any, TParent = any>(strings: TemplateStringsArray, ...values: TemplateValue<TSource, TParent>[]) => ViewTemplate<TSource, TParent>) & {
+    /**
+     * Transforms a template literal string into partial HTML.
+     * @param html - The HTML string fragment to interpolate.
+     * @public
+     */
+    partial(html: string): InlineTemplateDirective;
+};
+
 /**
  * The standard View implementation, which also implements ElementView and SyntheticView.
  * @public
@@ -1591,6 +1581,29 @@ export declare class HTMLView<TSource = any, TParent = any> implements ElementVi
     static disposeContiguousBatch(views: SyntheticView[]): void;
 }
 
+/**
+ * Inlines a template into another template.
+ * @public
+ */
+export declare class InlineTemplateDirective implements HTMLDirective {
+    private html;
+    private factories;
+    /**
+     * An empty template partial.
+     */
+    static readonly empty: InlineTemplateDirective;
+    /**
+     * Creates an instance of InlineTemplateDirective.
+     * @param template - The template to inline.
+     */
+    constructor(html: string, factories?: Record<string, ViewBehaviorFactory>);
+    /**
+     * Creates HTML to be used within a template.
+     * @param add - Can be used to add  behavior factories to a template.
+     */
+    createHTML(add: AddViewBehaviorFactory): string;
+}
+
 /**
  * Observes array lengths.
  * @public
@@ -1650,8 +1663,6 @@ export declare const Markup: Readonly<{
     comment: (id: string) => string;
 }>;
 
-/* Excluded from this release type: Mutable */
-
 /**
  * Options for configuring node observation behavior.
  * @public
@@ -1783,6 +1794,12 @@ export declare interface Notifier {
     unsubscribe(subscriber: Subscriber, propertyToUnwatch?: any): void;
 }
 
+/**
+ * A {@link ValueConverter} that converts to and from `boolean` values. `null`, `undefined`, `""`, and `void` values are converted to `null`.
+ * @public
+ */
+export declare const nullableBooleanConverter: ValueConverter;
+
 /**
  * A {@link ValueConverter} that converts to and from `number` values.
  * @remarks
@@ -2522,6 +2539,10 @@ export declare interface SyntheticViewTemplate<TSource = any, TParent = any> {
      * Creates a SyntheticView instance based on this template definition.
      */
     create(): SyntheticView<TSource, TParent>;
+    /**
+     * Returns a directive that can inline the template.
+     */
+    inline(): CaptureType<TSource, TParent>;
 }
 
 /**
@@ -2530,6 +2551,18 @@ export declare interface SyntheticViewTemplate<TSource = any, TParent = any> {
  */
 export declare type TemplateValue<TSource, TParent = any> = Expression<TSource, any, TParent> | Binding<TSource, any, TParent> | HTMLDirective | CaptureType<TSource, TParent>;
 
+/**
+ * A policy for use with the standard trustedTypes platform API.
+ * @public
+ */
+export declare type TrustedTypesPolicy = {
+    /**
+     * Creates trusted HTML.
+     * @param html - The HTML to clear as trustworthy.
+     */
+    createHTML(html: string): string;
+};
+
 /* Excluded from this release type: TypeDefinition */
 
 /* Excluded from this release type: TypeRegistry */
@@ -2704,6 +2737,10 @@ export declare class ViewTemplate<TSource = any, TParent = any> implements Eleme
      * @param hostBindingTarget - The element that host behaviors will be bound to.
      */
     create(hostBindingTarget?: Element): HTMLView<TSource, TParent>;
+    /**
+     * Returns a directive that can inline the template.
+     */
+    inline(): CaptureType<TSource, TParent>;
     /**
      * Sets the DOMPolicy for this template.
      * @param policy - The policy to associated with this template.

package/dist/fast-element.debug.js

@@ -107,14 +107,17 @@ switch (kernelMode) {
         break;
 }
 /**
+ * Determines whether or not an object is a function.
  * @internal
  */
 const isFunction = (object) => typeof object === "function";
 /**
+ * Determines whether or not an object is a string.
  * @internal
  */
 const isString = (object) => typeof object === "string";
 /**
+ * A function which does nothing.
  * @internal
  */
 const noop = () => void 0;
@@ -235,72 +238,6 @@ function createMetadataLocator() {
     };
 }
 
-/**
- * The default UpdateQueue.
- * @public
- */
-const Updates = FAST.getById(KernelServiceId.updateQueue, () => {
-    const tasks = [];
-    const pendingErrors = [];
-    const rAF = globalThis.requestAnimationFrame;
-    let updateAsync = true;
-    function throwFirstError() {
-        if (pendingErrors.length) {
-            throw pendingErrors.shift();
-        }
-    }
-    function tryRunTask(task) {
-        try {
-            task.call();
-        }
-        catch (error) {
-            if (updateAsync) {
-                pendingErrors.push(error);
-                setTimeout(throwFirstError, 0);
-            }
-            else {
-                tasks.length = 0;
-                throw error;
-            }
-        }
-    }
-    function process() {
-        const capacity = 1024;
-        let index = 0;
-        while (index < tasks.length) {
-            tryRunTask(tasks[index]);
-            index++;
-            // Prevent leaking memory for long chains of recursive calls to `enqueue`.
-            // If we call `enqueue` within a task scheduled by `enqueue`, the queue will
-            // grow, but to avoid an O(n) walk for every task we execute, we don't
-            // shift tasks off the queue after they have been executed.
-            // Instead, we periodically shift 1024 tasks off the queue.
-            if (index > capacity) {
-                // Manually shift all values starting at the index back to the
-                // beginning of the queue.
-                for (let scan = 0, newLength = tasks.length - index; scan < newLength; scan++) {
-                    tasks[scan] = tasks[scan + index];
-                }
-                tasks.length -= index;
-                index = 0;
-            }
-        }
-        tasks.length = 0;
-    }
-    function enqueue(callable) {
-        tasks.push(callable);
-        if (tasks.length < 2) {
-            updateAsync ? rAF(process) : process();
-        }
-    }
-    return Object.freeze({
-        enqueue,
-        next: () => new Promise(enqueue),
-        process,
-        setMode: (isAsync) => (updateAsync = isAsync),
-    });
-});
-
 /**
  * The type of HTML aspect to target.
  * @public
@@ -353,21 +290,6 @@ const fastPolicy = defaultPolicy;
  * @public
  */
 const DOM = Object.freeze({
-    /**
-     * @deprecated
-     * Use Updates.enqueue().
-     */
-    queueUpdate: Updates.enqueue,
-    /**
-     * @deprecated
-     * Use Updates.next()
-     */
-    nextUpdate: Updates.next,
-    /**
-     * @deprecated
-     * Use Updates.process()
-     */
-    processUpdates: Updates.process,
     /**
      * Gets the dom policy used by the templating system.
      */
@@ -751,6 +673,72 @@ const DOMPolicy = Object.freeze({
     },
 });
 
+/**
+ * The default UpdateQueue.
+ * @public
+ */
+const Updates = FAST.getById(KernelServiceId.updateQueue, () => {
+    const tasks = [];
+    const pendingErrors = [];
+    const rAF = globalThis.requestAnimationFrame;
+    let updateAsync = true;
+    function throwFirstError() {
+        if (pendingErrors.length) {
+            throw pendingErrors.shift();
+        }
+    }
+    function tryRunTask(task) {
+        try {
+            task.call();
+        }
+        catch (error) {
+            if (updateAsync) {
+                pendingErrors.push(error);
+                setTimeout(throwFirstError, 0);
+            }
+            else {
+                tasks.length = 0;
+                throw error;
+            }
+        }
+    }
+    function process() {
+        const capacity = 1024;
+        let index = 0;
+        while (index < tasks.length) {
+            tryRunTask(tasks[index]);
+            index++;
+            // Prevent leaking memory for long chains of recursive calls to `enqueue`.
+            // If we call `enqueue` within a task scheduled by `enqueue`, the queue will
+            // grow, but to avoid an O(n) walk for every task we execute, we don't
+            // shift tasks off the queue after they have been executed.
+            // Instead, we periodically shift 1024 tasks off the queue.
+            if (index > capacity) {
+                // Manually shift all values starting at the index back to the
+                // beginning of the queue.
+                for (let scan = 0, newLength = tasks.length - index; scan < newLength; scan++) {
+                    tasks[scan] = tasks[scan + index];
+                }
+                tasks.length -= index;
+                index = 0;
+            }
+        }
+        tasks.length = 0;
+    }
+    function enqueue(callable) {
+        tasks.push(callable);
+        if (tasks.length < 2) {
+            updateAsync ? rAF(process) : process();
+        }
+    }
+    return Object.freeze({
+        enqueue,
+        next: () => new Promise(enqueue),
+        process,
+        setMode: (isAsync) => (updateAsync = isAsync),
+    });
+});
+
 /**
  * An implementation of {@link Notifier} that efficiently keeps track of
  * subscribers interested in a specific change notification on an
@@ -2031,11 +2019,6 @@ css.partial = (strings, ...values) => {
     const { styles, behaviors } = collectStyles(strings, values);
     return new CSSPartial(styles, behaviors);
 };
-/**
- * @deprecated Use css.partial instead.
- * @public
- */
-const cssPartial = css.partial;
 
 const marker = `fast-${Math.random().toString(36).substring(2, 8)}`;
 const interpolationStart = `${marker}{`;
@@ -3018,6 +3001,37 @@ const Compiler = {
 const lastAttributeNameRegex = 
 /* eslint-disable-next-line no-control-regex */
 /([ \x09\x0a\x0c\x0d])([^\0-\x1F\x7F-\x9F "'>=/]+)([ \x09\x0a\x0c\x0d]*=[ \x09\x0a\x0c\x0d]*(?:[^ \x09\x0a\x0c\x0d"'`<>=]*|"[^"]*|'[^']*))$/;
+const noFactories = Object.create(null);
+/**
+ * Inlines a template into another template.
+ * @public
+ */
+class InlineTemplateDirective {
+    /**
+     * Creates an instance of InlineTemplateDirective.
+     * @param template - The template to inline.
+     */
+    constructor(html, factories = noFactories) {
+        this.html = html;
+        this.factories = factories;
+    }
+    /**
+     * Creates HTML to be used within a template.
+     * @param add - Can be used to add  behavior factories to a template.
+     */
+    createHTML(add) {
+        const factories = this.factories;
+        for (const key in factories) {
+            add(factories[key]);
+        }
+        return this.html;
+    }
+}
+/**
+ * An empty template partial.
+ */
+InlineTemplateDirective.empty = new InlineTemplateDirective("");
+HTMLDirective.define(InlineTemplateDirective);
 function createHTML(value, prevString, add, definition = HTMLDirective.getForInstance(value)) {
     if (definition.aspected) {
         const match = lastAttributeNameRegex.exec(prevString);
@@ -3059,6 +3073,12 @@ class ViewTemplate {
         }
         return this.result.createView(hostBindingTarget);
     }
+    /**
+     * Returns a directive that can inline the template.
+     */
+    inline() {
+        return new InlineTemplateDirective(isString(this.html) ? this.html : this.html.innerHTML, this.factories);
+    }
     /**
      * Sets the DOMPolicy for this template.
      * @param policy - The policy to associated with this template.
@@ -3141,12 +3161,15 @@ class ViewTemplate {
  * other template instances, and Directive instances.
  * @public
  */
-function html(strings, ...values) {
+const html = ((strings, ...values) => {
     if (Array.isArray(strings) && Array.isArray(strings.raw)) {
         return ViewTemplate.create(strings, values);
     }
     throw FAST.error(1206 /* Message.directCallToHTMLTagNotAllowed */);
-}
+});
+html.partial = (html) => {
+    return new InlineTemplateDirective(html);
+};
 
 /**
  * The runtime behavior for template references.
@@ -3642,29 +3665,6 @@ function children(propertyOrOptions) {
     return new ChildrenDirective(propertyOrOptions);
 }
 
-/**
- * A directive capable of injecting static HTML platform runtime protection.
- * @public
- */
-class DangerousHTMLDirective {
-    constructor(html) {
-        this.html = html;
-    }
-    createHTML() {
-        return this.html;
-    }
-}
-HTMLDirective.define(DangerousHTMLDirective);
-/**
- * Injects static HTML without platform protection.
- * @param html - The html to injection.
- * @returns A DangerousHTMLDirective.
- * @public
- */
-function dangerousHTML(html) {
-    return new DangerousHTMLDirective(html);
-}
-
 const booleanMode = "boolean";
 const reflectMode = "reflect";
 /**
@@ -3697,6 +3697,20 @@ const booleanConverter = {
             : true;
     },
 };
+/**
+ * A {@link ValueConverter} that converts to and from `boolean` values. `null`, `undefined`, `""`, and `void` values are converted to `null`.
+ * @public
+ */
+const nullableBooleanConverter = {
+    toView(value) {
+        return typeof value === "boolean" ? value.toString() : "";
+    },
+    fromView(value) {
+        return [null, undefined, void 0].includes(value)
+            ? null
+            : booleanConverter.fromView(value);
+    },
+};
 function toNumber(value) {
     if (value === null || value === undefined) {
         return null;
@@ -4527,4 +4541,4 @@ function customElement(nameOrDef) {
 
 DOM.setPolicy(DOMPolicy.create());
 
-export { ArrayObserver, AttributeConfiguration, AttributeDefinition, Binding, CSSDirective, ChildrenDirective, Compiler, DOM, DOMAspect, DangerousHTMLDirective, ElementController, ElementStyles, ExecutionContext, FAST, FASTElement, FASTElementDefinition, HTMLBindingDirective, HTMLDirective, HTMLView, Markup, NodeObservationDirective, Observable, Parser, PropertyChangeNotifier, RefDirective, RepeatBehavior, RepeatDirective, SlottedDirective, SourceLifetime, Splice, SpliceStrategy, SpliceStrategySupport, StatelessAttachedAttributeDirective, SubscriberSet, Updates, ViewTemplate, attr, bind, booleanConverter, children, createMetadataLocator, createTypeRegistry, css, cssDirective, cssPartial, customElement, dangerousHTML, elements, emptyArray, html, htmlDirective, lengthOf, listener, normalizeBinding, nullableNumberConverter, observable, oneTime, ref, repeat, slotted, volatile, when };
+export { ArrayObserver, AttributeConfiguration, AttributeDefinition, Binding, CSSDirective, ChildrenDirective, Compiler, DOM, DOMAspect, ElementController, ElementStyles, ExecutionContext, FAST, FASTElement, FASTElementDefinition, HTMLBindingDirective, HTMLDirective, HTMLView, InlineTemplateDirective, Markup, NodeObservationDirective, Observable, Parser, PropertyChangeNotifier, RefDirective, RepeatBehavior, RepeatDirective, SlottedDirective, SourceLifetime, Splice, SpliceStrategy, SpliceStrategySupport, StatelessAttachedAttributeDirective, SubscriberSet, Updates, ViewTemplate, attr, bind, booleanConverter, children, createMetadataLocator, createTypeRegistry, css, cssDirective, customElement, elements, emptyArray, html, htmlDirective, lengthOf, listener, normalizeBinding, nullableBooleanConverter, nullableNumberConverter, observable, oneTime, ref, repeat, slotted, volatile, when };