Rewrite v3 Getting Started docs#7569
Draft
radium-v wants to merge 6 commits into
Draft
Conversation
radium-v
changed the title
There was a problem hiding this comment.
Pull request overview
This PR rewrites and expands the FAST Element v3 documentation site’s getting-started content, adds a new DOM Policy guide, and introduces prev/next pagination derived from the Eleventy navigation tree. It also tweaks the website dev workflow by enabling Eleventy incremental builds in watch mode.
Changes:
- Reworked v3 getting-started docs (Quick Start, FASTElement, HTML Templates) and added navigation ordering.
- Added a new v3 advanced “DOM Policies” guide and linked it from template/security guidance.
- Implemented prev/next pagination UI (Nunjucks include + CSS) and added a
prevNextEleventy filter; enabled--incrementalin the site start script.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| sites/website/src/docs/3.x/getting-started/quick-start.md | Rewritten Quick Start guide; introduces tsconfig guidance and an end-to-end component example. |
| sites/website/src/docs/3.x/getting-started/html-templates.md | Expanded template authoring/binding reference, including DOMPolicy mention and host bindings. |
| sites/website/src/docs/3.x/getting-started/fast-element.md | Reworked FASTElement overview; adds lifecycle/define/compose guidance and controller notes. |
| sites/website/src/docs/3.x/advanced/dom-policy.md | New DOMPolicy advanced guide describing Trusted Types integration and withPolicy(). |
| sites/website/src/css/main.css | Adds pagination navigation styling and hides pagination in print. |
| sites/website/src/_includes/pagination-nav.njk | New prev/next pagination include driven by eleventy-navigation ordering. |
| sites/website/src/_includes/3x-container.njk | Renders pagination include for v3 pages. |
| sites/website/package.json | Adds --incremental to Eleventy serve/watch startup script. |
| sites/website/eleventy.config.js | Adds a prevNext filter to compute siblings from the navigation tree. |
| "module": "ESNext", | ||
| "moduleResolution": "Bundler", | ||
| "target": "ES2022", | ||
| "useDefineForClassFields": false // should be false when targeting ES2022 or newer (see FAST#5261) |
Comment on lines
+67
to
+70
| class HelloWorld extends FASTElement { | ||
| @attr | ||
| name: string; | ||
| } |
Comment on lines
148
to
151
| class HelloWorld extends FASTElement { | ||
| @attr | ||
| name: string; | ||
| @attr | ||
| name?: string; | ||
| } |
Comment on lines
+154
to
+156
| ### Event Bindings | ||
|
|
||
| Event bindings are used to attach event listeners to elements within the template. They are denoted by prefixing an attribute binding with an at symbol (`@`). The value returned by the binding function is expected to be a function, which is registered as an event listener for the specified event type. |
Comment on lines
+140
to
+142
| :::tip | ||
| FAST's `Observable` API can be used independently of custom elements, so you can create observable objects and properties in any JavaScript class, not just those that extend `FASTElement`. Read the [Reactivity](/docs/advanced/reactivity.md) section for more details on using observables in FAST. | ||
| ::: |
Comment on lines
+193
to
195
| :::note | ||
| Overriding `connectedCallback` can affect the timing of when your template is bound and when behaviors run, so it's generally recommended to call `super.connectedCallback()` at the beginning of your override. Conversely, for `disconnectedCallback` and `attributeChangedCallback`, it's usually best to call the super method at the end of your override to ensure that your custom logic runs while the element is still in a consistent state. | ||
| ::: |
Comment on lines
+37
to
+43
| const trustedType = trustedTypes.createPolicy("my-app", { | ||
| createHTML(value) { | ||
| // Run the value through a sanitizer such as DOMPurify | ||
| // before returning it. | ||
| return sanitize(value); | ||
| }, | ||
| }); |
|
|
||
| This guide assumes you're building a browser bundle with TypeScript, via a build tool such as esbuild, Rollup, Vite, or Webpack. | ||
|
|
||
| Install `@microsoft/fast-element` as a dev dependency: |
|
|
||
| ```bash | ||
| npm install --save @microsoft/fast-element | ||
| npm install --save-dev @microsoft/fast-element |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull Request
📖 Description
Rewrites and expands the FAST Element v3 documentation site. The getting-started guides were dense and in places out of date; this branch reworks them and adds the missing DOM Policy reference.
--incrementalflag to the website's watch mode so local rebuilds are faster.📑 Test Plan
Everything here touches
sites/website/**(content, Eleventy config, styles). Runnpm run startinsites/website, then check the updated pages render and the prev/next navigation links to the right neighbors. All existing tests pass.✅ Checklist
General