💬 RFC: add onboarding docs geared at newcomers to web components or JS framework devs, to fast.design

[usrrname]

Context

This request comes about from discussions I’ve had with @rajsite on the steep learning gradient Javascript framework developers who may also be new to web components experience when onboarding to use FAST.

I propose collaborating on a documents to address the following topics with the goal of:

• allowing JS framework developers to become productive sooner when contributing to design systems that use FAST by offering mental models that differentiate web components from the internal logic and way-of-working with Angular and React.
• enable JS devs who are new to web components to comfortably identify differences between web component syntax and leverage FAST features to build components, faster.

The following are topics I suggest adding articles, codeblocks or tutorials for are a result of common questions I've received from onboarding teams of 5-20 at work to contribute components to a design system built with "@microsoft/fast-element": "2.0.0-beta.18" and "@microsoft/fast-foundation": "3.0.0-alpha.22"

Related Discord threads: 1, 2, 3, 4

Related: #6527 but Rob asked me to create a RFC to track this.

Potential Topics

• What are web components and what does FAST have to do with it?

  • What is the role of shadow DOM in web components?
  • How can I use CSS to target elements in Shadow DOM?
  • What the shadow DOM is not.
  • How does rendering of FAST web components differ from rendering in Angular or React?
    • How does the native Shadow DOM differ from Angular's ViewEncapsulation Shadow DOM?
    • How does rendering in React's Virtual DOM differ to that of FAST?
  • How can I mitigate Flash of Unstyled Custom Element (FOUCE) with FAST?
  • Which package should I import to:
    • extend an existing Fast component?
    • build a custom component?
    • Do I still need to use the @customElement directive?

• How FAST accelerates component development instead of writing vanilla JS web components

  • @observables instead of static getObservedAttributes()
  • using @attr to define (custom) attributes to make them available on the custom element markup level
  • conditional rendering with when, ViewTemplates and @observable
  • the role of named and unnamed slots, the slotted directive, and the role of defaultSlottedContent property in existing FAST components and FASTElement, and how that impacts component architecture
  • the inheritance of web component lifecycle events like connectedCallback() in FASTElement that require calling super() in extended components to leverage inherited class methods.
  • the relationship between FAST type definitions and the HTML Living Standard and W3C spec.

• How do event lifecycles in FAST differ from handling events in Angular or React?

  Example Stackblitz showing:

  • calling upon super.<inheritedMethod>() in a class method
  • event binding on templates and the @<event> syntax
  • The JS Proxy object and its role in events, getting and setting of inherited attributes in FAST components like FASTButton
  • usage of$emit for dispatching custom events within the light DOM.

• How to prepare form field components so that work inside a form element?
  Example Stackblitz demonstrating preparation of Text Field as a Form Associated Custom Element. Related: Add form-associated components documentation. #3536
  To Be Offered:

  • Integrating the Text Field into Angular (14)
  • Integrating the Text Field into React (18)

  Other lifecycle topics:

  • the role of Updates.enqueue() to queue the application of changes on re-renders

• Configuring FAST components to close or disable the Shadow DOM/ only support Light DOM

  • The implications of disabling or closing the Shadow DOM
    Example: article and Stackblitz with fast-foundation components to prototype these attempts in "Closing, Cloning, or Disabling the Shadow DOM"

  Note: I know there is already advice on the doc site, but the above subject came up so much at work in comparison with Stencil with all-or-nothing ideas about implementing components with shadow DOM; I believe we could supply explainers of the implications of “disabling” or “closing” the shadow DOM and offer ways to work with event emitting or scoping styles for shadow DOM instead

💻 Examples

The following typologises existing industry examples of onboarding JS developers to onboard, adopt or migrate frameworks:

The FAQ style page:

• “How Does Stencil Compare to Traditional Frameworks? | Stencil Frequently Asked Questions” StencilJS Docs. 2023
• "Knowledge Level Assumptions", React, 2023.

The Framework Comparison:

• “All the Ways To Build a Web Component”, webcomponents.dev by <div> riots, Feb 17, 2022.
• Marius Bogarts, “Will Web Components Replace Front end Frameworks?”, Web Highlights, Oct 26, 2022
• Dave Rupert, "Comparing Web Component Libraries", HTML with Super Powers, 2023.
• Burton Smith. (@break-stuff) "Custom Forms with Web Components and "ElementInternals""

Conceptual Translations
Familiar mental models that developers comfortable with non-web-component frameworks can use to ramp up faster:

• Angular.io, "Angular - Content Projection", Feb 28 2022
• Ryan Merill @procload, "Web components and Angular"
• Sandro Roth, "Building Component Slots in React", Oct 31, 2022.

The tutorial series with code clips:

• Tebin Raouf (@tebinraouf) , “Building Web Components 101: Part 1 of 4”, Dev.to. Feb 17, 2022
• Simon MacDonald (@macdonst) , “Using Fast Components in an Enhance App”, Dev.to, Jan 20, 2023.
• NextJS. “Building Forms with Next.js”, 2023
• Dave Rupert, "Styling Light DOM", HTML with Super Powers , 2023

The Table-of-contents for Incremental Code-along Learning

• Lit. "Lit.dev Tutorials", 2023.
• “Developing Components: Code Examples”, Open Web Components, 2023.
• “Migrating from Gatsby | Next.js”, 2023.

Recommended Testing Integrations

• Playwright setup

[janechu]

This is being addressed in the v2 @microsoft/fast-element documentation that is soon to be released. Closing the issue for now but please re-open or open a new issue after the launch if you feel the documentation could be more clear.