Add working with decorators doc and updated api-report markdown (#7012)

# Pull Request

## 📖 Description

This change adds a document on working without decorators.

### 🎫 Issues

Closes #6376

## ✅ Checklist

### General

<!--- Review the list and put an x in the boxes that apply. -->

- [x] I have included a change request file using `$ npm run change`
- [ ] I have added tests for my changes.
- [x] I have tested my changes.
- [x] I have updated the project documentation to reflect my changes.
- [x] I have read the [CONTRIBUTING](https://github.com/microsoft/fast/blob/master/CONTRIBUTING.md) documentation and followed the [standards](https://github.com/microsoft/fast/blob/master/CODE_OF_CONDUCT.md#our-standards) for this project.

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": "7559015+janechu@users.noreply.github.com",
+ "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,