UI Architecture

[ctapobep]

• Directory structure
• Components
• HTML Layout
• JS Modules
• Approaches that we DON'T use
  • Why we don't use MVC frameworks like React, Angular or Vue
  • Why not Web Components

Directory structure

For a good example of page structure & components look in Peaksel at GlobalSettings page.

css (styles in 03_xxx can override 02_xxx which in turn can override those in 01_xxx)
   |_01_globals.css (default styles of standard HTML elements, fonts, variables)
   |_01_helpers.css (some commonly used classes which aren't related to any component)
   |_02_xxx.css (a set of BEM classes used to define common elements like buttons, tables, etc. which aren't JS Components)
   |_...

js (Domain logic, repositories, utils, etc. Isn't part of any particular UI component)
   |_somepackage
      |_SomeClass.js
      |_...

components
   |_ComonentName
      |_SubComponent (if it's "private" - we don't want to re-use it in other places)
         |_ ...
      |_ComponentName.css
      |_ComponentNameCmp.js (public API of the component, doesn't talk about "HTML" or "DOM")
      |_ComponentNameHtml.js (all about "HTML" and "DOM")
      |_AnotherPotentialClass.js

pages
   |_SomePage
      |_PrivateComponent (we don't want to reuse it on other pages)
      |_SomePage.html
      |_SomePage.js
      |_SomePageIoC.js

Components

A typical component consist of 2 JS files (XxxCmp and XxxHtml):

class SomeCmp {
    #html = new SomeHtml();
    #children = {}; // we could initialize some private sub-components right in the field, but some of them have to be injected using DI
    #someRepository;
    #someEventCb = () => {};// a callback
    
    // accepts non-HTML parts so that it could be created by Dependency Injection
    constructor(someOtherComponent, someRepository) {
        this.#someRepository = someRepository;
        this.#children.someOtherComponent = someOtherComponent;
    }

    // accepts HTML-specific data so that it could be initialized by some other components in their context
    init(parentDomElement) {
         this.#html.init(parentDomElement);
         this.onSomeHtmlEvent(this.#onSomeHtmlEvent.bind(this));
         this.#children.someOtherComponent.init(this.#html.getParentForSomeChild());
    }

    // Public API of the component to subscribe to its events. Components shouldn't talk in terms of DOM!
    onSomeEvent(cb) {
         this.#someEventCb = cb;
    }

    // this is our listener that's subscribed to whatever #html has to say
    #onSomeHtmlEvent(someData) { 
         this.#someEventCb(convertToSomething(someData)); 
    }
}

HTML Layout

1. Use semantics of HTML5 (h1, h2, h3, nav, main, footer, header, menu, dialog, etc.). Tags <div> and <span> must be our last resort.
2. When defining some tag for the components Parent Element, in HTLM we use some custom tags: <some-component>. This isn't a Web Component (see below)! Browsers treat unrecognized tags just fine. But we have to have at least one - in the tag. This is the convention that separates browser-native tags from our custom ones.
3. Don't use document.queryBySelector('.className'). Prefer tag-name for custom components, name or other attributes for standard components. Classes should be used only in CSS.

JS Modules

In the new code we're supposed to use JavaScript modules: import instead of require(), as well as export and export default.

Approaches that we DON'T use

Why we don't use MVC frameworks like React, Angular or Vue

We don't use MVC frameworks on UI in order to:

1. Keep learning curve low:
   • We want to encourage Full Stack developers - so that the Back End devs could easily learn JS and start UI coding
   • We'll have scientists-who-want-to-code joining our team at some point - for them learning MVC frameworks could be quite an endeavour
2. Promote fundamental skills. It's more important to learn very well how JS works rather than study a new MVC framework each year. JS is a transferable skill, while today's new an shiny MVC framework may be replaced with a new one the next day.
3. These frameworks don't speed up developers as much as they used to. These days JS has string interpolation which allows us to create readable HTML templates.
4. Even if standard components of MVC frameworks are used, it's often that after some years of development projects start needing a more customized behaviour. And we'd have to implement a lot of custom components anyway.
5. Very fast build process. Tools like React need to have an additional build step to transform their layout language into code. Angular is supposed to be used in TypeScript and therefore requires a transpiling step. These are additional complications and slowing factors.

Having said that, there are some things that we're missing out on:

1. MVVM. A lot of MVC frameworks allow to bind variables to form elements. Changing one then changes the other. We may want to look into specialized frameworks or write something ourselves tiny for this.
2. Libraries of components. While we would've written a lot of custom components anyway, a lot of standard ones may still be widely used our software. Also, it's better to have a standard component and customize it later. Rather than having to write a custom component right away.

Why not Web Components

Web Components is an attempt of to implement HTML-native components. We define a custom tag <some-component> and then separately in JS we define which JS class implements it. Unfortunately, this approach has big problems:

1. It works inside a shadow root. Meaning the insides of this component aren't visible to the outside elements and vice versa. This means that we can't use global CSS (like tag default styles, variables, etc). Without additional preprocessing this doesn't let us re-use a lot of code.
2. Each component loads its own CSS. This means that when creating a component (e.g. opening a dialog), browser has to go to the server. Because we usually want to this to be done asynchronously, first elements are rendered w/o styles. Then browser loads them styles and applies them. But user can still see the HTML blinking and changing.
3. The same async loading also causes issues in our code. E.g. if we want to put focus into some input, but that input hasn't finished initializing yet. So if we focus right away and the the styles are loaded, the focus is getting lost. So in our code we have to delay the focusing by some milliseconds - which is ugly and unreliable.

So instead to isolate the styles of components we use BEM.