From 5629f15064225b3227bbf88e99ca3495d5832c56 Mon Sep 17 00:00:00 2001 From: Jane Chu <7559015+janechu@users.noreply.github.com> Date: Fri, 2 Aug 2024 09:05:50 -0700 Subject: [PATCH 1/2] Remove the component libraries doc which is empty (#7013) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Pull Request ## 📖 Description This change removes the component library document. This will be written in the future, but we will go without it pre-launch of fast element 2.0. ## ✅ Checklist ### General - [ ] I have included a change request file using `$ npm run change` - [ ] I have added tests for my changes. - [ ] 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. --- sites/website/sidebars.js | 1 - sites/website/src/docs/advanced/component-libraries.md | 9 --------- 2 files changed, 10 deletions(-) delete mode 100644 sites/website/src/docs/advanced/component-libraries.md diff --git a/sites/website/sidebars.js b/sites/website/sidebars.js index c393fe3143b..a3c2373393e 100644 --- a/sites/website/sidebars.js +++ b/sites/website/sidebars.js @@ -41,7 +41,6 @@ module.exports = { }, items: [ "advanced/working-with-custom-elements", - "advanced/component-libraries", "advanced/dependency-injection", ], }, diff --git a/sites/website/src/docs/advanced/component-libraries.md b/sites/website/src/docs/advanced/component-libraries.md deleted file mode 100644 index 2a3bf121ca1..00000000000 --- a/sites/website/src/docs/advanced/component-libraries.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -id: component-libraries -title: Component Libraries -sidebar_label: Component Libraries -keywords: - - component libraries ---- - -// TODO \ No newline at end of file From 92e82f74b9ec0e5eb28895a6aba6426224ee434d Mon Sep 17 00:00:00 2001 From: Jane Chu <7559015+janechu@users.noreply.github.com> Date: Fri, 2 Aug 2024 09:56:15 -0700 Subject: [PATCH 2/2] Add working with decorators doc and updated api-report markdown (#7012) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Pull Request ## 📖 Description This change adds a document on working without decorators. ### 🎫 Issues Closes #6376 ## ✅ Checklist ### General - [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. --- ...-ffdf0a73-daa4-462a-bc2f-60a25ce2066f.json | 7 ++ .../fast-element/api-extractor.context.json | 2 +- .../fast-element/api-extractor.di.json | 2 +- .../{api-report.md => api-report.api.md} | 2 +- .../di/{api-report.md => api-report.api.md} | 0 sites/website/sidebars.js | 1 + .../advanced/working-without-decorators.md | 90 +++++++++++++++++++ sites/website/src/docs/integrations.md | 2 +- 8 files changed, 102 insertions(+), 4 deletions(-) create mode 100644 change/@microsoft-fast-element-ffdf0a73-daa4-462a-bc2f-60a25ce2066f.json rename packages/web-components/fast-element/docs/context/{api-report.md => api-report.api.md} (98%) rename packages/web-components/fast-element/docs/di/{api-report.md => api-report.api.md} (100%) create mode 100644 sites/website/src/docs/advanced/working-without-decorators.md diff --git a/change/@microsoft-fast-element-ffdf0a73-daa4-462a-bc2f-60a25ce2066f.json b/change/@microsoft-fast-element-ffdf0a73-daa4-462a-bc2f-60a25ce2066f.json new file mode 100644 index 00000000000..8a942f4ff8c --- /dev/null +++ b/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" +} diff --git a/packages/web-components/fast-element/api-extractor.context.json b/packages/web-components/fast-element/api-extractor.context.json index 96748e457b0..b9c3b28e30b 100644 --- a/packages/web-components/fast-element/api-extractor.context.json +++ b/packages/web-components/fast-element/api-extractor.context.json @@ -5,7 +5,7 @@ "apiReport": { "enabled": true, "reportFolder": "/docs/context", - "reportFileName": "api-report.md" + "reportFileName": "api-report" }, "docModel": { "enabled": true, diff --git a/packages/web-components/fast-element/api-extractor.di.json b/packages/web-components/fast-element/api-extractor.di.json index eb937082a00..3deb3f8f9f7 100644 --- a/packages/web-components/fast-element/api-extractor.di.json +++ b/packages/web-components/fast-element/api-extractor.di.json @@ -5,7 +5,7 @@ "apiReport": { "enabled": true, "reportFolder": "/docs/di", - "reportFileName": "api-report.md" + "reportFileName": "api-report" }, "docModel": { "enabled": true, diff --git a/packages/web-components/fast-element/docs/context/api-report.md b/packages/web-components/fast-element/docs/context/api-report.api.md similarity index 98% rename from packages/web-components/fast-element/docs/context/api-report.md rename to packages/web-components/fast-element/docs/context/api-report.api.md index 8e3e2f53b22..f7d84f5f86e 100644 --- a/packages/web-components/fast-element/docs/context/api-report.md +++ b/packages/web-components/fast-element/docs/context/api-report.api.md @@ -27,7 +27,7 @@ export const Context: Readonly<{ // @public export type ContextCallback = (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 = Readonly> & PropertyDecorator & ParameterDecorator_2; diff --git a/packages/web-components/fast-element/docs/di/api-report.md b/packages/web-components/fast-element/docs/di/api-report.api.md similarity index 100% rename from packages/web-components/fast-element/docs/di/api-report.md rename to packages/web-components/fast-element/docs/di/api-report.api.md diff --git a/sites/website/sidebars.js b/sites/website/sidebars.js index a3c2373393e..af651d2218a 100644 --- a/sites/website/sidebars.js +++ b/sites/website/sidebars.js @@ -41,6 +41,7 @@ module.exports = { }, items: [ "advanced/working-with-custom-elements", + "advanced/working-without-decorators", "advanced/dependency-injection", ], }, diff --git a/sites/website/src/docs/advanced/working-without-decorators.md b/sites/website/src/docs/advanced/working-without-decorators.md new file mode 100644 index 00000000000..527a4077ed0 --- /dev/null +++ b/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`
${(x) => x.count}
`, + styles: css`div { background: red }`, + attributes: [ + 'count', + ], + }; +} + +FASTElement.define(MyElement); +``` + +```html + +``` + +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`
${(x) => x.currentCount}
`, + 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`
${(x) => x.currentCount}
`, + styles: css`div { background: red }`, + attributes: [ + { + attribute: 'current-count', + property: 'currentCount', + converter + }, + ], + }; + + currentCount = 42; +} + +FASTElement.define(MyElement); +``` \ No newline at end of file diff --git a/sites/website/src/docs/integrations.md b/sites/website/src/docs/integrations.md index ea63699f5a4..a8ec92becd6 100644 --- a/sites/website/src/docs/integrations.md +++ b/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,