Add working with decorators doc and updated api-report markdown

change/@microsoft-fast-element-ffdf0a73-daa4-462a-bc2f-60a25ce2066f.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Add working with decorators doc and updated api-report markdown",
+  "packageName": "@microsoft/fast-element",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

packages/web-components/fast-element/api-extractor.context.json

@@ -5,7 +5,7 @@
     "apiReport": {
         "enabled": true,
         "reportFolder": "<projectFolder>/docs/context",
-        "reportFileName": "api-report.md"
+        "reportFileName": "api-report"
     },
     "docModel": {
         "enabled": true,

packages/web-components/fast-element/api-extractor.di.json

@@ -5,7 +5,7 @@
     "apiReport": {
         "enabled": true,
         "reportFolder": "<projectFolder>/docs/di",
-        "reportFileName": "api-report.md"
+        "reportFileName": "api-report"
     },
     "docModel": {
         "enabled": true,

packages/web-components/fast-element/docs/context/api-report.md → packages/web-components/fast-element/docs/context/api-report.api.md

@@ -27,7 +27,7 @@ export const Context: Readonly<{
 // @public
 export type ContextCallback<ValueType> = (value: ValueType, dispose?: () => void) => void;
 
-// Warning: (ae-forgotten-export) The symbol "ParameterDecorator" needs to be exported by the entry point context.d.ts
+// Warning: (ae-forgotten-export) The symbol "ParameterDecorator_2" needs to be exported by the entry point context.d.ts
 //
 // @public
 export type ContextDecorator<T = any> = Readonly<Context<T>> & PropertyDecorator & ParameterDecorator_2;

sites/website/sidebars.js

@@ -41,6 +41,7 @@ module.exports = {
             },
             items: [
                 "advanced/working-with-custom-elements",
+                "advanced/working-without-decorators",
                 "advanced/dependency-injection",
             ],
         },

sites/website/src/docs/advanced/working-without-decorators.md

@@ -0,0 +1,90 @@
+---
+id: working-without-decorators
+title: Working without Decorators
+sidebar_label: Working without Decorators
+keywords:
+  - decorators
+---
+
+Most of our documented examples include the use of TypeScript decorators. However, as decorators are an unimplemented feature in JavaScript, using them may not be right for your project. See [TypeScript documentation](https://www.typescriptlang.org/docs/handbook/decorators.html) for details on our implementation.
+
+The static `definition` accepts the same configuration options as the `@attr` decorator. For example, to bind a property name that is different from an attribute name:
+
+```javascript
+import { FASTElement, html, css } from '@microsoft/fast-element';
+
+export class MyElement extends FASTElement {
+  static definition = {
+    name: 'my-element',
+    template: html`<div>${(x) => x.count}</div>`,
+    styles: css`div { background: red }`,
+    attributes: [
+      'count',
+    ],
+  };
+}
+
+FASTElement.define(MyElement);
+```
+
+```html
+<my-element count="42">
+```
+
+This accepts the same configuration options as the `@attr` so for example to bind a property name that is different from an attribute name:
+
+```javascript
+import { FASTElement, html, css } from '@microsoft/fast-element';
+
+export class MyElement extends FASTElement {
+  static definition = {
+    name: 'my-element',
+    template: html`<div>${(x) => x.currentCount}</div>`,
+    styles: css`div { background: red }`,
+    attributes: [
+      {
+        attribute: 'current-count',
+        property: 'currentCount'
+      },
+    ],
+  };
+
+  currentCount = 42;
+}
+
+FASTElement.define(MyElement);
+```
+
+If you need to add a converter to your attribute:
+
+```javascript
+import { FASTElement, html, css } from '@microsoft/fast-element';
+
+const converter = {
+  toView: (value) => {
+    return value / 2;
+  },
+  fromView: (value) => {
+    return value / 2;
+  },
+};
+
+export class MyElement extends FASTElement {
+  static definition = {
+    name: 'my-element',
+    template: html`<div>${(x) => x.currentCount}</div>`,
+    styles: css`div { background: red }`,
+    attributes: [
+      {
+        attribute: 'current-count',
+        property: 'currentCount',
+        converter
+      },
+    ],
+  };
+
+  currentCount = 42;
+}
+
+FASTElement.define(MyElement);
+```

sites/website/src/docs/integrations.md

@@ -243,7 +243,7 @@ Here's an example starter `taconfig.json` that you can use:
     "target": "ES2015",
     "module": "ES2015",
     "moduleResolution": "node",
-    "importHelpers": true,
+    "importHelpers": true, // when using decorators this allows for the smallest footprint using tslib
     "experimentalDecorators": true,
     "declaration": true,
     "declarationMap": true,