As I understand there are basically two(+) ways of definining components in FAST.
I will provide my own answer to the question below, what I want to verify is whether I am correctly understanding the differences and if there is anything to add.
What I've found out so far:
🐢 One - Immediate Template & Style Resolution
FASTElement
from @microsoft/fast-element
@customElement
decorator from @microsoft/fast-element
-
in its name@customElement
decorator) are immediately resolvedExample pseudocode (parts from official docs):
const counterStyles = css`/* ... */`;
const counterTemplate = html<NameTag>`<!-- ... -->`;
@customElement({
name: 'name-tag',
counterTemplate,
counterStyles,
shadowOptions:
})
export class NameTag extends FASTElement {
@attr name = "Sally";
}
🐅 Two - Extendible and Lazy Template & Style Resolution
Foundationelement
from @microsoft/fast-foundation
-
in its name (since it will be prepended with the prefix of a DesignSystem
that will register it)compose
method that is made available to the component through its FoundationElement
base classExample pseudocode (parts from official docs):
export class Counter extends FoundationElement {
@attr count = 0;
increment() {
this.count++;
}
}
/* if CounterDefinition wouldny be defined then expressions below would use FoundationElementDefinition instead*/
interface CounterDefinition extends FoundationElementDefinition {
defaultButtonContent?: string;
defaultButtonColour?: string;
}
const counterStyles = (
context: ElementDefinitionContext,
definition: CounterDefinition
) => css`/* ... */`;
const counterTemplate = (
context: ElementDefinitionContext,
definition: CounterDefinition
) => html`<!-- ... -->`;
export const counter = Counter.compose<CounterDefinition>({
baseName: 'counter',
counterTemplate,
counterStyles,
defaultButtonContent: "Count!",
defaultButtonColour: "pink"
});
🦆 Three/One+ - Kindof One but without decorators?
One
but without decorators, meaning it cannot lazily resolve its styles and templatesThe distinctions you call out are correct for the most part.
The first mechanism is intended to be what folks use most commonly when building components in their application. It immediately associates the template and styles with the element and then immediately registers the component with the web platform itself.
The second mechanism was intended primarily for those building design systems where they want to provide the system to others and enable those consumers to customize parts of the system before using it. So, it allows for lazily providing parts of the template, altering styles, etc.
This second mechanism is deprecated in the upcoming 2.0/3.0 set of release. The reasons for this are:
Please let me encourage you to read this issue: https://github.com/microsoft/fast/issues/5901 I go into greater depth on the problems and motivations related to this question as well as paint a picture of the future we are working towards with the upcoming new versions.
Related to defining and registering componnets, you'll want to keep a few considerations in mind: