@microsoft/fast-element 2.0.0-beta.9 → 2.0.0

package/docs/guide/defining-elements.md

@@ -1,214 +0,0 @@
----
-id: defining-elements
-title: Defining Elements
-sidebar_label: Defining Elements
-custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-element/docs/guide/defining-elements.md
-description: To define a custom element, begin by creating a class that extends FASTElement and decorate it with the @customElement decorator, providing the element name.
----
-
-## Basic elements
-
-To define a custom element, begin by creating a class that extends `FASTElement` and decorate it with the `@customElement` decorator, providing the element name.
-
-**Example: A Basic `FASTElement` Definition**
-
-```ts
-import { FASTElement, customElement } from '@microsoft/fast-element';
-
-@customElement('name-tag')
-export class NameTag extends FASTElement {
-
-}
-```
-
-With this in place, you can now use your `name-tag` element anywhere in HTML with the following markup:
-
-**Example: Using a Web Component**
-
-```html
-<name-tag></name-tag>
-```
-
-:::important
-Web Component names must contain a `-` in order to prevent future conflicts with built-in elements and to namespace components from different libraries. For more information on the basics of Web Components [see this set of articles](https://developers.google.com/web/fundamentals/web-components).
-:::
-
-:::note
-HTML has a few special tags known as "self-closing tags". Common examples include `<input>` and `<img>`. However, most HTML elements and **all** web components must have an explicit closing tag.
-:::
-
-We've got a basic Web Component in place, but it doesn't do much. So, let's add an attribute and make it render something. 
-
-**Example: Adding Attributes to a `FASTElement`**
-
-```ts
-import { FASTElement, customElement, attr } from '@microsoft/fast-element';
-
-@customElement('name-tag')
-export class NameTag extends FASTElement {
-  @attr greeting: string = 'Hello';
-
-  // optional method 
-  greetingChanged() {
-    ...
-  }
-}
-```
-
-To add attributes to your HTML element, create properties decorated by the `@attr` decorator. All attributes defined this way will be automatically registered with the platform so that they can be updated through the browser's native `setAttribute` API as well as the property. You can optionally add a method with the naming convention *propertyName*Changed to your class (e.g. `greeting` and `greetingChanged()`), and this method will be called whenever your property changes, whether it changes through the property or the attribute API.
-
-:::note
-All properties decorated with `@attr` are also *observable*. See [observables and state](./observables-and-state.md) for information about how observables enable efficient rendering.
-:::
-
-By default, anything extending from `FASTElement` will automatically have a `ShadowRoot` attached in order to enable encapsulated rendering. 
-
-To see it in action, you can use the same HTML as above, or change the default `greeting` with the following:
-
-**Example: Using a Web Component with Attributes**
-
-```html
-<name-tag greeting="Hola"></name-tag>
-```
-
-## Customizing attributes
-
-By default, any attribute created with `@attr` will perform no explicit type coercion other than when it reflects its value to the HTML DOM via the `setAttribute` API. However, you can convert DOM attribute string values to and from arbitrary types as well as control the `mode` that is used to reflect property values to the DOM. There are three modes available through the `mode` property of the attribute configuration:
-
-* `reflect` - The *default* mode that is used if none is specified. This reflects property changes to the DOM. If a `converter` is supplied, it will invoke the converter before calling the `setAttribute` DOM API.
-* `boolean` - This mode causes your attribute to function using the HTML boolean attribute behavior. When your attribute is present in the DOM or equal to its own name, the value will be true. When the attribute is absent from the DOM, the value of the property will be false. Setting the property will also update the DOM by adding/removing the attribute.
-* `fromView` - This mode skips reflecting the value of the property back to the HTML attribute, but does receive updates when changed through `setAttribute`.
-
-In addition to setting the `mode`, you can also supply a custom `ValueConverter` by setting the `converter` property of the attribute configuration. The converter must implement the following interface:
-
-```ts
-interface ValueConverter {
-    toView(value: any): string;
-    fromView(value: string): any;
-}
-```
-
-Here's how it works:
-
-* When the DOM attribute value changes, the converter's `fromView` method will be called, allowing custom code to coerce the value to the proper type expected by the property.
-* When the property value changes, the converter's `fromView` method will also be called, ensuring that the type is correct. After this, the `mode` will be determined. If the mode is set to `reflect` then the converter's `toView` method will be called to allow the type to be formatted before writing to the attribute using `setAttribute`.
-
-:::important
-When the `mode` is set to `boolean`, a built-in `booleanConverter` is automatically used to ensure type correctness so that the manual configuration of the converter is not needed in this common scenario.
-:::
-
-**Example: An Attribute in Reflect Mode with No Special Conversion**
-
-```ts
-import { FASTElement, customElement, attr } from '@microsoft/fast-element';
-
-@customElement('name-tag')
-export class NameTag extends FASTElement {
-  @attr greeting: string = 'Hello';
-}
-```
-
-**Example: An Attribute in Boolean Mode with Boolean Conversion**
-
-```ts
-import { FASTElement, customElement, attr } from '@microsoft/fast-element';
-
-@customElement('my-checkbox')
-export class MyCheckbox extends FASTElement {
-  @attr({ mode: 'boolean' }) disabled: boolean = false;
-}
-```
-
-**Example: An Attribute in Reflect Mode with Custom Conversion**
-
-```ts
-import { FASTElement, customElement, attr, ValueConverter } from '@microsoft/fast-element';
-
-const numberConverter: ValueConverter = {
-  toView(value: any): string {
-    // convert numbers to strings
-  },
-
-  fromView(value: string): any {
-    // convert strings to numbers
-  }
-};
-
-@customElement('my-counter')
-export class MyCounter extends FASTElement {
-  @attr({ converter: numberConverter }) count: number = 0;
-}
-```
-
-## The element lifecycle
-
-All Web Components support a series of lifecycle events that you can tap into to execute custom code at specific points in time. `FASTElement` implements several of these callbacks automatically in order to enable features of its templating engine (described in [declaring templates](./declaring-templates.md)). However, you can override them to provide your own code. Here's an example of how you would execute custom code when your element is inserted into the DOM.
-
-**Example: Tapping into the Custom Element Lifecycle**
-
-```ts
-import { FASTElement, customElement, attr } from '@microsoft/fast-element';
-
-@customElement('name-tag')
-export class NameTag extends FASTElement {
-  @attr greeting: string = 'Hello';
-
-  greetingChanged() {
-    this.shadowRoot!.innerHTML = this.greeting;
-  }
-
-  connectedCallback() {
-    super.connectedCallback();
-    console.log('name-tag is now connected to the DOM');
-  }
-}
-```
-
-The full list of available lifecycle callbacks is:
-
-| Callback | Description |
-| ------------- |-------------|
-| constructor | Runs when the element is created or upgraded. `FASTElement` will attach the shadow DOM at this time. |
-| connectedCallback | Runs when the element is inserted into the DOM. On first connect, `FASTElement` hydrates the HTML template, connects template bindings, and adds the styles. |
-| disconnectedCallback | Runs when the element is removed from the DOM. `FASTElement` will remove template bindings and clean up resources at this time. |
-| attributeChangedCallback(attrName, oldVal, newVal) | Runs any time one of the element's custom attributes changes. `FASTElement` uses this to sync the attribute with its property. When the property updates, a render update is also queued, if there was a template dependency. |
-| adoptedCallback | Runs if the element was moved from its current `document` into a new `document` via a call to the `adoptNode(...)` API. |
-
-## Working without decorators
-
-The examples above and those throughout our documentation leverage TypeScript, and in particular, the decorators feature of the language. Decorators are an upcoming feature planned for a future version of JavaScript, but their design is not yet finished. While the syntax for decorator usage is not likely to change in the final version of the feature, some of our community members may feel uncomfortable using this feature at this stage. Additionally, since decorators are transpiled into code that uses helper functions (both in TypeScript and Babel) the compiled output will be larger than the equivalent non-decorator code.
-
-While there are size implications of using decorators prior to full language support, they do present the most declarative and readable form of the API, and we recommend their use for the average project. To strike a balance between declarative readability and size, we recommend that TypeScript be used in combination with the `"importHelpers": true` compiler option. When this option is set, instead of generating helper functions for decorators into every file, TypeScript will import a set of shared helpers published in the `tslib` package.
-
-For those that require the smallest possible builds, FAST Elements can be completely defined in Vanilla JS, without using decorators, by leveraging a static `definition` field on your class. The `definition` field only needs to present the same configuration as the `@customElement` decorator. Here's an example that shows the use of the `definition` field along with a manual call to `define` the element:
-
-```js
-import { FASTElement, html, css } from '@microsoft/fast-element';
-
-const template = html`...`;
-const styles = css`...`;
-const converter = { ... };
-
-export class MyElement extends FASTElement {
-  static definition = {
-    name: 'my-element',
-    template,
-    styles,
-    attributes: [
-      'value', // same attr/prop
-      { attribute: 'some-attr', property: 'someAttr' }, // different attr/prop
-      { property: 'count', converter } // derive attr; add converter
-    ]
-  };
-
-  value = '';
-  someAttr = '';
-  count = 0;
-}
-
-FASTElement.define(MyElement);
-```
-
-:::note
-The `definition` can also be separated from the class and passed into the `define` call directly if desired. Here's what that would look like: `FASTElement.define(MyElement, myDefinition);`
-:::

package/docs/guide/leveraging-css.md

@@ -1,253 +0,0 @@
----
-id: leveraging-css
-title: Leveraging CSS
-sidebar_label: Leveraging CSS
-custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-element/docs/guide/leveraging-css.md
-description: Similar to HTML, FASTElement provides a css tagged template helper to allow creating and re-using CSS.
----
-
-## Basic styles
-
-The final piece of our component story is CSS. Similar to HTML, `FASTElement` provides a `css` tagged template helper to allow creating and re-using CSS. Let's add some CSS for our `name-tag` component.
-
-**Example: Adding CSS to a `FASTElement`**
-
-```ts
-import { html, css, customElement, attr, FASTElement } from "@microsoft/fast-element";
-
-const template = html<NameTag>`
-  <div class="header">
-    <slot name="avatar"></slot>
-    <h3>${x => x.greeting.toUpperCase()}</h3>
-    <h4>my name is</h4>
-  </div>
-
-  <div class="body">
-    <slot></slot>
-  </div>
-
-  <div class="footer"></div>
-`;
-
-const styles = css`
-  :host {
-    display: inline-block;
-    contain: content;
-    color: white;
-    background: var(--fill-color);
-    border-radius: var(--border-radius);
-    min-width: 325px;
-    text-align: center;
-    box-shadow: 0 0 calc(var(--depth) * 1px) rgba(0,0,0,.5);
-  }
-
-  :host([hidden]) { 
-    display: none;
-  }
-
-  .header {
-    margin: 16px 0;
-    position: relative;
-  }
-
-  h3 {
-    font-weight: bold;
-    font-family: 'Source Sans Pro';
-    letter-spacing: 4px;
-    font-size: 32px;
-    margin: 0;
-    padding: 0;
-  }
-
-  h4 {
-    font-family: sans-serif;
-    font-size: 18px;
-    margin: 0;
-    padding: 0;
-  }
-
-  .body {
-    background: white;
-    color: black;
-    padding: 32px 8px;
-    font-size: 42px;
-    font-family: cursive;
-  }
-
-  .footer {
-    height: 16px;
-    background: var(--fill-color);
-    border-radius: 0 0 var(--border-radius) var(--border-radius);
-  }
-`;
-
-@customElement({
-  name: 'name-tag',
-  template,
-  styles
-})
-export class NameTag extends FASTElement {
-  @attr greeting: string = 'Hello';
-}
-```
-
-Using the `css` helper, we're able to create `ElementStyles`. We configure this with the element through the `styles` option of the decorator. Internally, `FASTElement` will leverage [Constructable Stylesheet Objects](https://wicg.github.io/construct-stylesheets/) and `ShadowRoot#adoptedStyleSheets` to efficiently re-use CSS across components. This means that even if we have 1k instances of our `name-tag` component, they will all share a single instance of the associated styles, allowing for reduced memory allocation and improved performance. Because the styles are associated with the `ShadowRoot`, they will also be encapsulated. This ensures that your styles don't affect other elements and other element styles don't affect your element.
-
-:::note
-We've used [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) throughout our CSS as well as [CSS Calc](https://developer.mozilla.org/en-US/docs/Web/CSS/calc) in order to enable our component to be styled in basic ways by consumers. Additionally, consider adding [CSS Shadow Parts](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) to your template, to enable even more powerful customization.
-:::
-
-## Composing styles
-
-One of the nice features of `ElementStyles` is that it can be composed with other styles. Imagine that we had a CSS normalize that we wanted to use in our `name-tag` component. We could compose that into our styles like this:
-
-**Example: Composing CSS Registries**
-
-```ts
-import { normalize } from './normalize';
-
-const styles = css`
-  ${normalize}
-  :host {
-    display: inline-block;
-    contain: content;
-    color: white;
-    background: var(--fill-color);
-    border-radius: var(--border-radius);
-    min-width: 325px;
-    text-align: center;
-    box-shadow: 0 0 calc(var(--depth) * 1px) rgba(0,0,0,.5);
-  }
-
-  ...
-`;
-```
-
-Rather than simply concatenating CSS strings, the `css` helper understands that `normalize` is `ElementStyles` and is able to re-use the same Constructable StyleSheet instance as any other component that uses `normalize`. 
-
-:::note
-You can also pass a CSS `string` or a [CSSStyleSheet](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet) instance directly to the element definition, or even a mixed array of `string`, `CSSStyleSheet`, or `ElementStyles`.
-:::
-
-### Partial CSS
-There are times when you may want to create reusable blocks of *partial* CSS, where the abstraction is not valid CSS in and of itself, such as groups of CSS properties or a complex value. To do that, you can use the `cssPartial` tagged template literal: 
-
-```ts
-import { css, cssPartial } from "@microsoft/fast-element";
-
-const partial = cssPartial`color: red;`;
-const styles = css`:host{ ${partial} }`;
-```
-
-`cssPartial` can also compose all structures that `css` can compose, providing even greater flexibility.
-
-## CSSDirective
-The `CSSDirective` allows binding behavior to an element via `ElementStyles`. To create a `CSSDirective`, import and extend `CSSDirective` from `@microsoft/fast-element`:
-
-```ts
-import { CSSDirective }  from "@microsoft/fast-element"
-
-class RandomWidth extends CSSDirective {}
-```
-
-A CSS directive has two key methods that you can leverage to add dynamic behavior via CSS:
-
-### createCSS
-`CSSDirective` has a `createCSS()` method that returns a string to be interpolated into an `ElementStyles`:
-
-```ts
-class RandomWidth extends CSSDirective {
-  createCSS() {
-    return "width: var(--random-width);"
-  }
-}
-```
-
-### createBehavior
-The `createBehavior()` method can be used to create a `Behavior` that is bound to the element using the `CSSDirective`:
-
-
-```ts
-class RandomWidth extends CSSDirective {
-  private property = "--random-width";
-  createCSS() {
-    return `width: var(${this.property});`
-  }
-
-  createBehavior() {
-    return {
-      bind(el) {
-        el.style.setProperty(this.property, Math.random() * 100)
-      }
-      unbind(el) {
-        el.style.removeProperty(this.property);
-      }
-    }
-  }
-}
-```
-
-### Usage in ElementStyles
-The `CSSDirective` can then be used in an `ElementStyles`, where the CSS string from `createCSS()` will be interpolated into the stylesheet, and the behavior returned from `createBehavior()` will get bound to the element using the stylesheet:
-
-```ts
-const styles = css`:host {${new RandomWidth()}}`;
-```
-
-## Shadow DOM styling
-
-You may have noticed the `:host` selector we used in our `name-tag` styles. This selector allows us to apply styles directly to our custom element. Here are a few things to consider always configuring for your host element:
-
-* **display** - By default, the `display` property of a custom element is `inline`, so consider whether you want your element's default display behavior to be different.
-* **contain** - If your element's painting is contained within its bounds, consider setting the CSS `contain` property to `content`. The right containment model can positively affect your element's performance. [See the MDN docs](https://developer.mozilla.org/en-US/docs/web/css/contain) for more information on the various values of `contain` and what they do. 
-* **hidden** - In addition to a default `display` style, add support for `hidden` so that your default `display` does not override this state. This can be done with `:host([hidden]) { display: none }`.
-
-## Slotted content
-
-In addition to providing host styles, you can also provide default styles for content that gets slotted. For example, if we wanted to style all `img` elements that were slotted into our `name-tag`, we could do it like this:
-
-**Example: Slotted Styles**
-
-```ts
-const styles = css`
-  ...
-
-  ::slotted(img) {
-    border-radius: 50%;
-    height: 64px;
-    width: 64px;
-    box-shadow: 0 0 calc(var(--depth) / 2px) rgba(0,0,0,.5);
-    position: absolute;
-    left: 16px;
-    top: -4px;
-  }
-
-  ...
-`;
-```
-
-:::note
-Both slotted and host styles can be overridden by the element user. Think of these as the *default* styles that you are providing, so that your elements look and function correctly out-of-the-box.
-:::
-
-## Styles and the element lifecycle
-
-It is during the `connectedCallback` phase of the Custom Element lifecycle that `FASTElement` adds the element's styles. The styles are only added the first time the element is connected.
-
-In most cases, the styles that `FASTElement` renders are determined by the `styles` property of the Custom Element's configuration. However, you can also implement a method on your Custom Element class named `resolveStyles()` that returns an `ElementStyles` instance. If this method is present, it will be called during `connectedCallback` to obtain the styles to use. This allows the element author to dynamically select completely different styles based on the state of the element at the time of connection.
-
-In addition to dynamic style selection during the `connectedCallback`, the `$fastController` property of `FASTElement` enables dynamically changing the styles at any time through setting the controller's `styles` property to any valid styles.
-
-### Hiding undefined elements
-
-Custom Elements that have not been [upgraded](https://developers.google.com/web/fundamentals/web-components/customelements#upgrades) and don't have styles attached can still be rendered by the browser but they likely do not look how they are supposed to. To avoid a *flash of un-styled content* (FOUC), visually hide Custom Elements if they have not been *defined*:
-
-```CSS
-:not(:defined) {
-  visibility: hidden;
-}
-```
-
-:::important
-The consuming application must apply this, as the components themselves do not.
-:::

package/docs/guide/next-steps.md

@@ -1,13 +0,0 @@
----
-id: next-steps
-title: Next Steps
-sidebar_label: Next Steps
-custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-element/docs/guide/next-steps.md
-description: Now that you're familiar with the robust and powerful features of FASTElement, you're ready to build your own components and apps.
----
-
-We've seen how to use `FASTElement` to declaratively build Web Components. In addition to the basics of element and attribute definition, `FASTElement` also provides a way to declare templates capable of high-performance rendering, and efficient, incremental batched updates. Finally, CSS can easily be associated with an element in a way that leverages core platform optimizations for performance and low memory allocation.
-
-Now that you're familiar with the robust and powerful features of `FASTElement`, you're ready to build your own components and apps. But you don't have to start from scratch there either! If you haven't already explored them, check out our [FAST Components](../components/getting-started.md), which provide all the basic UI building-blocks you'd expect in a modern component library. You can also leverage the same adaptive design system that our own components use to enable robust theming throughout all you create. Read more on that in [Styling Components](../design-systems/fast-frame.md#configuring-components). Finally, you'll want to take advantage of a modern toolset by installing [a powerful editor and plugins](../tools/vscode.md).
-
-For a quick reference, check out [our Cheat Sheet](../resources/cheat-sheet.md).