Questions about the component system

[eomine]

Hi @graphicore , as I mentioned, I have a few questions about the component system, so I'm creating this public discussion. Hopefully, we can turn this into documentation later.

_BaseComponent

_BaseComponent seems to be the most essential class to be extended when creating a new component.

Subclasses with no HTML output

Examples: UIVisibilityManager and MonitorPlayingState.

I assume they extend _BaseComponent simply to be able to access the widgetBus and therefore read/write some property in the application state, is that correct?

Subclasses with HTML output

Example: ToggleFullscreen.

A common implementation is having a static TEMPLATE property and a _initTemplate method that builds the component's HTML and returns an array containing the elements used in the rest of the subclass.

Some of these components create HTML children dynamically inside _initTemplate, but I couldn't find any that instantiates other components (or widgets as they are called when they appear in the codebase).

Note: not a big issue, but I think using a single name, either "component" or "widget", to refer to these entities would make it easier to read the codebase.

_BaseContainerComponent

_BaseContainerComponent seems to be the solution to components that must instantiate other components, is that correct?

But I couldn't find any subclass of _BaseContainerComponent that also has a template. When a _BaseContainerComponent creates HTML elements, it does so through the DOMTool, not using a template, is that correct?

Would it be possible for a _BaseContainerComponent to have a templated part in the current implementation?

Because one of the things I wanted to do for the new sidebar design was creating a new AppMenu component that has "static" parts (like the title "TypeRoof" and the links to documentation, GitHub, etc) but also instantiates other components (the layout selector and the dialog opener for the serialization / deserialization dialog). With the current component system, I understand that:

• AppMenu has to be a _BaseContainerComponent subclass;
• The static parts have to be created programatically using the DOMTool;
• If I don't want to create children programatically, I have to create another component with a template and then instantiate it from AppMenu.

_CommonContainerComponent

I see _BaseContainerComponent extends _CommonContainerComponent, and implements methods _provisionWidgets and initialUpdate. I noticed only a few components in the codebase extend _CommonContainerComponent directly instead of _BaseContainerComponent. It would be nice to understand the difference between those classes and what the use case for each of them is.

[graphicore]

Thanks @eomine for starting this. I will add some more remarks to your observarions:

_BaseComponent

_BaseComponent seems to be the most essential class to be extended when creating a new component.

It serves as it mostly as a "leave" in a tree of components. As a leave, Subclasses of this don't spawn other components. Though, the important disambiguation it has to the _CommonContainerComponent is that it sets [UPDATE_STRATEGY] = UPDATE_STRATEGY_SIMPLE; which changes the signature of the update function. This is not a strict requirement, a sub-class can also change it's UPDATE_STRATEGY. UPDATE_STRATEGY_SIMPLE means update(changedMap) where, the items in changedMap are the dependencies that are set in the widget definition. update is only called if there are items in changedMap and the items in changedMap are only the changed items since the last update. Initially, changedMap will contain all dependencies at the current state. There's also a pattern that has emerged, where a component may require items even if they didn't change, like this:

const globalT = (changedMap.has('globalT')
                        ? changedMap.get('globalT')
                        : this.getEntry('globalT')).value

The implementation of UPDATE_STRATEGY is in updateWidget(widgetWrapper, compareResult, requiresFullInitialUpdate, isInitialUpdate) of _CommonContainerComponent which is fundamental to the component system.

Subclasses with no HTML output

I assume they extend _BaseComponent simply to be able to access the widgetBus and therefore read/write some property in the application state, is that correct?

Generally, with "access to the widgetBus" comes the power the read state, to get notified when state changes, and to write state.

There's another way, how components can play a role, which allows for a lot of flexibility, but also must be used with consideration, as it can become confusing. A component can have an id set via it's settings. That id is not fully global, but within the current branch of components, within the container that created it, it can be queried. That allows for "services" that cannot or don't need to be connected with by the Metamodel-state. I.e. any (public) interface of such a component could be used. UIVisibilityManager is actually an example of this id based intercourse, although it also uses widgetBus in a very specialized way. ProseMirrorContext is connecting some widgets that have optional extended behavior if some id's exist.

Another example for no HTML is AnimationTGenerator its purpose is to change the global t value using requestAnimationFrame, as well as to start and stop the animation of t. It's not creating any html itself, instead it's controlled by setting other properties like playing: boolean or duration: number, perpetual: boolean, and it also reacts to changes of t: number.

Subclasses with HTML output

A common implementation is having a static TEMPLATE property and a _initTemplate method that builds the component's HTML and returns an array containing the elements used in the rest of the subclass.

Right. It is not required to use an _initTemplate method. Also note, usually the HTML is created in the constructor, the constructor often uses an _initTemplate method for this and the HTML directly inserted using this._insertElement method, which is connected to the zone setting. Also note, with the .typeroof.jsx flavor for example, we change the static TEMPLATE approach to jsx. There's not enforced way on how to create HTML, just patterns that are used. All of the html is created via DOMTool, but that convention is mainly to ensure the correct document is used, e.g. with iframes we can have the same code controlling different documents, or we might not have a native, global document e.g. in nodejs.

Some of these components create HTML children dynamically inside _initTemplate, but I couldn't find any that instantiates other components (or widgets as they are called when they appear in the codebase).

Yes right, the methods to instantiate other components are mainly in _CommonContainerComponent one very interesting method is also _provisionWidgets which get's a compareResult and creates and destroys it's children-components accordingly. _provisionWidgets is often customized for specific tasks, i.e. to create one child per item of a list vs. create all widgets that are explicitly defined in a configuration array. Note: e.g. in the list case also changes of order must be considered.

Note: not a big issue, but I think using a single name, either "component" or "widget", to refer to these entities would make it easier to read the codebase.

We could tackle this. In my mind everything is a component but widgets are components that provide a specific user interface element. widgetBus at least should thus rather be called componentBus but we can also ban the term widget altogether. If we don't ban it, we should take care that we call the right things widgets, which I did not do thoroughly. Generally the disambiguation I have between component and widget is probably newer than the uses of widget in the codebase, as initially, I rather did not think about components that are not widgets. It's never been a sharp distinction though.

_BaseContainerComponent

_BaseContainerComponent seems to be the solution to components that must instantiate other components, is that correct?

But I couldn't find any subclass of _BaseContainerComponent that also has a template. When a _BaseContainerComponent creates HTML elements, it does so through the DOMTool, not using a template, is that correct?

These are mainly just creating DOM-elements for their zones, which is rather simple to do.

Would it be possible for a _BaseContainerComponent to have a templated part in the current implementation?

Yes, absolutely. However, I would rather create specific leave type _BaseComponents when I have that need, and use ids to establish a connection. See e.g. _UIBaseMap It defines it it's _initialWidgets a widget this.constructor.UIKeyAddButton with an id: 'key-add-button' and passes a local event handler, it uses the id to control the 'passive' state of that widget. There are other examples, maybe better ones.
Also, to react within that widget directly to state changes, you would have to implement that yourself as _BaseContainerComponent uses UPDATE_STRATEGY_COMPARE.

Because one of the things I wanted to do for the new sidebar design was creating a new AppMenu component that has "static" parts (like the title "TypeRoof" and the links to documentation, GitHub, etc) but also instantiates other components (the layout selector and the dialog opener for the serialization / deserialization dialog). With the current component system, I understand that:

• AppMenu has to be a _BaseContainerComponent subclass;

If you need a customized _provsionWidgets method _CommonContainerComponent could be an option as well, depends a bit.

• The static parts have to be created programatically using the DOMTool;

Everything uses the DOMTool, you should at least use it to get document reference. If you use .typeroof.jsx you also use the DOMTool, it's just syntactic sugar.

• If I don't want to create children programatically, I have to create another component with a template and then instantiate it from AppMenu.

You can use a template directly, there's nothing special in how _BaseComponent does it, it's all custom implementations of a pattern that calls _initTemplate which itself usually calls this._domTool.createFragmentFromHTML(this.constructor.TEMPLATE).firstElementChild (in typeroof.jsx I started to use instead this._getTemplate(this._domTool.h) where _getTemplate contains the jsx-html) and this._insertElement

There are ways around this. For actual static markup, you can create it directly, but in order for _insertElement to work, the parent needs to define a zone. There are also in generic.mjs e.g. StaticNode or StaticTag if you want to insert these widgets by the means of the _BaseContainerComponent. If you want to have static and dynamic widgets in some fashion, you may need to define a _provsionWidgets method or maybe "decorate" an existing implementation etc.

_CommonContainerComponent

I see _BaseContainerComponent extends _CommonContainerComponent, and implements methods _provisionWidgets and initialUpdate. I noticed only a few components in the codebase extend _CommonContainerComponent directly instead of _BaseContainerComponent. It would be nice to understand the difference between those classes and what the use case for each of them is.

It would be a good idea to document different implementations of _provisionWidget as there are specific problems these try to solve, however, it's too specific for this answer. Likely whatever directly extends _CommonContainerComponent is probably foundational/important.