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

package/dist/dts/components/attributes.d.ts

@@ -40,6 +40,16 @@ export declare type AttributeConfiguration = {
     mode?: AttributeMode;
     converter?: ValueConverter;
 };
+/**
+ * Metadata used to configure a custom attribute's behavior.
+ * @public
+ */
+export declare const AttributeConfiguration: Readonly<{
+    /**
+     * Locates all attribute configurations associated with a type.
+     */
+    locate: (target: {}) => AttributeConfiguration[];
+}>;
 /**
  * Metadata used to configure a custom attribute's behavior through a decorator.
  * @public
@@ -52,6 +62,11 @@ export declare type DecoratorAttributeConfiguration = Omit<AttributeConfiguratio
  * @public
  */
 export declare const booleanConverter: ValueConverter;
+/**
+ * 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

package/dist/dts/components/{controller.d.ts → element-controller.d.ts}

@@ -1,21 +1,35 @@
-import type { Behavior } from "../observation/behavior.js";
 import { PropertyChangeNotifier } from "../observation/notifier.js";
-import type { ElementStyles } from "../styles/element-styles.js";
+import { ElementStyles } from "../styles/element-styles.js";
+import type { HostBehavior, HostController } from "../styles/host.js";
+import type { StyleStrategy, StyleTarget } from "../styles/style-strategy.js";
 import type { ElementViewTemplate } from "../templating/template.js";
 import type { ElementView } from "../templating/view.js";
 import { FASTElementDefinition } from "./fast-definitions.js";
+/**
+ * A type that instantiates an ElementController
+ * @public
+ */
+export interface ElementControllerStrategy {
+    new (element: HTMLElement, definition: FASTElementDefinition): ElementController;
+}
 /**
  * Controls the lifecycle and rendering of a `FASTElement`.
  * @public
  */
-export declare class Controller<TElement extends HTMLElement = HTMLElement> extends PropertyChangeNotifier {
+export declare class ElementController<TElement extends HTMLElement = HTMLElement> extends PropertyChangeNotifier implements HostController<TElement> {
     private boundObservables;
-    private behaviors;
     private needsInitialization;
     private hasExistingShadowRoot;
     private _template;
-    private _styles;
-    private _isConnected;
+    private stage;
+    /**
+     * A guard against connecting behaviors multiple times
+     * during connect in scenarios where a behavior adds
+     * another behavior during it's connectedCallback
+     */
+    private guardBehaviorConnection;
+    private behaviors;
+    private _mainStyles;
     /**
      * This allows Observable.getNotifier(...) to return the Controller
      * when the notifier for the Controller itself is being requested. The
@@ -28,7 +42,7 @@ export declare class Controller<TElement extends HTMLElement = HTMLElement> exte
     /**
      * The element being controlled by this controller.
      */
-    readonly element: TElement;
+    readonly source: TElement;
     /**
      * The element definition that instructs this controller
      * in how to handle rendering and other platform integrations.
@@ -45,7 +59,6 @@ export declare class Controller<TElement extends HTMLElement = HTMLElement> exte
      * connected to the document.
      */
     get isConnected(): boolean;
-    private setIsConnected;
     /**
      * Gets/sets the template used to render the component.
      * @remarks
@@ -54,12 +67,11 @@ export declare class Controller<TElement extends HTMLElement = HTMLElement> exte
     get template(): ElementViewTemplate<TElement> | null;
     set template(value: ElementViewTemplate<TElement> | null);
     /**
-     * Gets/sets the primary styles used for the component.
-     * @remarks
-     * This value can only be accurately read after connect but can be set at any time.
+     * The main set of styles used for the component, independent
+     * of any dynamically added styles.
      */
-    get styles(): ElementStyles | null;
-    set styles(value: ElementStyles | null);
+    get mainStyles(): ElementStyles | null;
+    set mainStyles(value: ElementStyles | null);
     /**
      * Creates a Controller to control the specified element.
      * @param element - The element to be controlled by this controller.
@@ -68,6 +80,17 @@ export declare class Controller<TElement extends HTMLElement = HTMLElement> exte
      * @internal
      */
     constructor(element: TElement, definition: FASTElementDefinition);
+    /**
+     * Adds the behavior to the component.
+     * @param behavior - The behavior to add.
+     */
+    addBehavior(behavior: HostBehavior<TElement>): void;
+    /**
+     * Removes the behavior from the component.
+     * @param behavior - The behavior to remove.
+     * @param force - Forces removal even if this behavior was added more than once.
+     */
+    removeBehavior(behavior: HostBehavior<TElement>, force?: boolean): void;
     /**
      * Adds styles to this element. Providing an HTMLStyleElement will attach the element instance to the shadowRoot.
      * @param styles - The styles to add.
@@ -78,25 +101,14 @@ export declare class Controller<TElement extends HTMLElement = HTMLElement> exte
      * @param styles - the styles to remove.
      */
     removeStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
-    /**
-     * Adds behaviors to this element.
-     * @param behaviors - The behaviors to add.
-     */
-    addBehaviors(behaviors: ReadonlyArray<Behavior<TElement>>): void;
-    /**
-     * Removes behaviors from this element.
-     * @param behaviors - The behaviors to remove.
-     * @param force - Forces unbinding of behaviors.
-     */
-    removeBehaviors(behaviors: ReadonlyArray<Behavior<TElement>>, force?: boolean): void;
     /**
      * Runs connected lifecycle behavior on the associated element.
      */
-    onConnectedCallback(): void;
+    connect(): void;
     /**
      * Runs disconnected lifecycle behavior on the associated element.
      */
-    onDisconnectedCallback(): void;
+    disconnect(): void;
     /**
      * Runs the attribute changed callback for the associated element.
      * @param name - The name of the attribute that changed.
@@ -113,7 +125,11 @@ export declare class Controller<TElement extends HTMLElement = HTMLElement> exte
      * Only emits events if connected.
      */
     emit(type: string, detail?: any, options?: Omit<CustomEventInit, "detail">): void | boolean;
-    private finishInitialization;
+    /**
+     * Opts out of JSON stringification.
+     * @internal
+     */
+    toJSON: () => undefined;
     private renderTemplate;
     /**
      * Locates or creates a controller for the specified element.
@@ -123,5 +139,35 @@ export declare class Controller<TElement extends HTMLElement = HTMLElement> exte
      * registered either through the use of the {@link customElement}
      * decorator or a call to `FASTElement.define`.
      */
-    static forCustomElement(element: HTMLElement): Controller;
+    static forCustomElement(element: HTMLElement): ElementController;
+    /**
+     * Sets the strategy that ElementController.forCustomElement uses to construct
+     * ElementController instances for an element.
+     * @param strategy - The strategy to use.
+     */
+    static setStrategy(strategy: ElementControllerStrategy): void;
+}
+/**
+ * https://wicg.github.io/construct-stylesheets/
+ * https://developers.google.com/web/updates/2019/02/constructable-stylesheets
+ *
+ * @internal
+ */
+export declare class AdoptedStyleSheetsStrategy implements StyleStrategy {
+    private static styleSheetCache;
+    /** @internal */
+    readonly sheets: CSSStyleSheet[];
+    constructor(styles: (string | CSSStyleSheet)[]);
+    addStylesTo(target: StyleTarget): void;
+    removeStylesFrom(target: StyleTarget): void;
+}
+/**
+ * @internal
+ */
+export declare class StyleElementStrategy implements StyleStrategy {
+    private readonly styles;
+    private readonly styleClass;
+    constructor(styles: string[]);
+    addStylesTo(target: StyleTarget): void;
+    removeStylesFrom(target: StyleTarget): void;
 }

package/dist/dts/components/fast-definitions.d.ts

@@ -2,6 +2,18 @@ import { Constructable } from "../interfaces.js";
 import { ComposableStyles, ElementStyles } from "../styles/element-styles.js";
 import type { ElementViewTemplate } from "../templating/template.js";
 import { AttributeConfiguration, AttributeDefinition } from "./attributes.js";
+/**
+ * Shadow root initialization options.
+ * @public
+ */
+export interface ShadowRootOptions extends ShadowRootInit {
+    /**
+     * A registry that provides the custom elements visible
+     * from within this shadow root.
+     * @beta
+     */
+    registry?: CustomElementRegistry;
+}
 /**
  * Represents metadata configuration for a custom element.
  * @public
@@ -25,19 +37,28 @@ export interface PartialFASTElementDefinition {
     readonly attributes?: (AttributeConfiguration | string)[];
     /**
      * Options controlling the creation of the custom element's shadow DOM.
+     * @remarks
+     * If not provided, defaults to an open shadow root. Provide null
+     * to render to the associated template to the light DOM instead.
      */
-    readonly shadowOptions?: Partial<ShadowRootInit> | null;
+    readonly shadowOptions?: Partial<ShadowRootOptions> | null;
     /**
      * Options controlling how the custom element is defined with the platform.
      */
     readonly elementOptions?: ElementDefinitionOptions;
+    /**
+     * The registry to register this component in by default.
+     * @remarks
+     * If not provided, defaults to the global registry.
+     */
+    readonly registry?: CustomElementRegistry;
 }
 /**
  * Defines metadata for a FASTElement.
  * @public
  */
 export declare class FASTElementDefinition<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>> {
-    private observedAttributes;
+    private platformDefined;
     /**
      * The type this element definition describes.
      */
@@ -73,18 +94,16 @@ export declare class FASTElementDefinition<TType extends Constructable<HTMLEleme
     /**
      * Options controlling the creation of the custom element's shadow DOM.
      */
-    readonly shadowOptions?: ShadowRootInit;
+    readonly shadowOptions?: ShadowRootOptions;
     /**
      * Options controlling how the custom element is defined with the platform.
      */
-    readonly elementOptions?: ElementDefinitionOptions;
+    readonly elementOptions: ElementDefinitionOptions;
     /**
-     * Creates an instance of FASTElementDefinition.
-     * @param type - The type this definition is being created for.
-     * @param nameOrConfig - The name of the element to define or a config object
-     * that describes the element to define.
+     * The registry to register this component in by default.
      */
-    constructor(type: TType, nameOrConfig?: PartialFASTElementDefinition | string);
+    readonly registry: CustomElementRegistry;
+    private constructor();
     /**
      * Defines a custom element based on this definition.
      * @param registry - The element registry to define the element in.
@@ -92,6 +111,19 @@ export declare class FASTElementDefinition<TType extends Constructable<HTMLEleme
      * This operation is idempotent per registry.
      */
     define(registry?: CustomElementRegistry): this;
+    /**
+     * Creates an instance of FASTElementDefinition.
+     * @param type - The type this definition is being created for.
+     * @param nameOrDef - The name of the element to define or a config object
+     * that describes the element to define.
+     */
+    static compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): FASTElementDefinition<TType>;
+    /**
+     * Registers a FASTElement base type.
+     * @param type - The type to register as a base type.
+     * @internal
+     */
+    static registerBaseType(type: Function): void;
     /**
      * Gets the element definition associated with the specified type.
      * @param type - The custom element type to retrieve the definition for.

package/dist/dts/components/fast-element.d.ts

@@ -1,5 +1,5 @@
-import type { Constructable } from "../interfaces.js";
-import { Controller } from "./controller.js";
+import { Constructable } from "../interfaces.js";
+import { ElementController } from "./element-controller.js";
 import { FASTElementDefinition, PartialFASTElementDefinition } from "./fast-definitions.js";
 /**
  * Represents a custom element based on the FASTElement infrastructure.
@@ -10,7 +10,7 @@ export interface FASTElement extends HTMLElement {
      * The underlying controller that handles the lifecycle and rendering of
      * this FASTElement.
      */
-    readonly $fastController: Controller;
+    readonly $fastController: ElementController;
     /**
      * Emits a custom HTML event.
      * @param type - The type name of the event.
@@ -45,34 +45,21 @@ export interface FASTElement extends HTMLElement {
      */
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }
+declare function compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(this: TType, nameOrDef: string | PartialFASTElementDefinition): FASTElementDefinition<TType>;
+declare function compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): FASTElementDefinition<TType>;
+declare function define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(this: TType, nameOrDef: string | PartialFASTElementDefinition): TType;
+declare function define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): TType;
+declare function from<TBase extends typeof HTMLElement>(BaseType: TBase): new () => InstanceType<TBase> & FASTElement;
 /**
  * A minimal base class for FASTElements that also provides
  * static helpers for working with FASTElements.
  * @public
  */
-export declare const FASTElement: (new () => HTMLElement & FASTElement) & {
-    /**
-     * Creates a new FASTElement base class inherited from the
-     * provided base type.
-     * @param BaseType - The base element type to inherit from.
-     */
-    from<TBase extends {
-        new (): HTMLElement;
-        prototype: HTMLElement;
-    }>(BaseType: TBase): new () => InstanceType<TBase> & FASTElement;
-    /**
-     * Defines a platform custom element based on the provided type and definition.
-     * @param type - The custom element type to define.
-     * @param nameOrDef - The name of the element to define or a definition object
-     * that describes the element to define.
-     */
-    define<TType extends Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): TType;
-    /**
-     * Defines metadata for a FASTElement which can be used to later define the element.
-     * IMPORTANT: This API will be renamed to "compose" in a future beta.
-     * @public
-     */
-    metadata<TType_1 extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType_1, nameOrDef?: string | PartialFASTElementDefinition): FASTElementDefinition<TType_1>;
+export declare const FASTElement: {
+    new (): FASTElement;
+    define: typeof define;
+    compose: typeof compose;
+    from: typeof from;
 };
 /**
  * Decorator: Defines a platform custom element based on `FASTElement`.
@@ -81,3 +68,4 @@ export declare const FASTElement: (new () => HTMLElement & FASTElement) & {
  * @public
  */
 export declare function customElement(nameOrDef: string | PartialFASTElementDefinition): (type: Constructable<HTMLElement>) => void;
+export {};

package/dist/dts/components/hydration.d.ts

@@ -0,0 +1,14 @@
+import { ElementController } from "./element-controller.js";
+/**
+ * An ElementController capable of hydrating FAST elements from
+ * Declarative Shadow DOM.
+ *
+ * @beta
+ */
+export declare class HydratableElementController<TElement extends HTMLElement = HTMLElement> extends ElementController<TElement> {
+    private static hydrationObserver;
+    private static hydrationObserverHandler;
+    connect(): void;
+    disconnect(): void;
+    static install(): void;
+}

package/dist/dts/context.d.ts

@@ -1,4 +1,4 @@
-import type { Constructable } from "./interfaces.js";
+import { Constructable } from "./interfaces.js";
 /**
  * A Context object defines an optional initial value for a Context, as well as a name identifier for debugging purposes.
  * @public