Framework Compatibility

Even though HelixUI strives to remain platform-agnostic, we also want to build functionality in a way that provides the least resistance for integration into a consumer's technology stack. As such, you should avoid implementing any business logic into new functionality (no API calls, no permission/authorization logic, no URLs, etc.).

The frameworks we aim for the most compatibility are:

• Vanilla HTML (i.e., no framework)
• Angular 1.x
• React 15+
• VueJS 2.x

Keep reading to learn more about framework compatibility issues and strategies to correct or work around them.

Vanilla HTML

(a.k.a. No framework)

• Be aware of built-in methods and properties of HTMLElement and its prototype chain.
  • Node ← Element ← HTMLElement
• WARNING: Be aware that autocomplete for forms has browser compatibility issues.
  • caniuse (autocomplete)
  • chromium bug (ignores autocomplete) - wontfix
  • chromium bug (valid use cases for autocomplete)
  • whatwg (autofill)

Angular 1.x

TBD

Angular 2+

@angular/cli

If you want use @angular/cli to bootstrap your application, you'll need to make sure to do the following to ensure maximum compatibility with HelixUI.

1. copy node_modules/helix-ui/ assets to src/assets/helix-ui/
2. copy node_modules/@webcomponents/webcomponentsjs/ assets to src/assets/webcomponentsjs/
3. update src/index.html contents with official Helix layout markup
4. make sure <link> and <scripts> in src/index.html point to files in src/assets/helix-ui and src/assets/webcomponentsjs
5. add CUSTOM_ELEMENTS_SCHEMA to the list of schemas in src/app/app.module.ts (see snippet below)

• Configures angular that to allow 3rd-party custom elements.

/* 
 * src/app/app.module.ts 
 */
import { BrowserModule } from '@angular/platform-browser';
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule
  ],
  providers: [],
  bootstrap: [AppComponent],
  schemas: [ CUSTOM_ELEMENTS_SCHEMA ]
})
export class AppModule { }

React 15+

• TODO: Using ref to attach event listeners
• (React 15, only) ... the slot attribute 🤦‍♂️
• Warning: React's synthetic events violate non-bubbling specifications.
  • It is a "known and intentional deviation".
  • See facebook/react#12786 and facebook/react#6410 for information.

React Component Lifecycle

All HTMLElement (custom element) lifecycle methods are executed in render()

Mount Phase

1. React.Component - constructor
2. React.Component - componentWillMount()
3. React.Component - render()
   1. HTMLElement - create/connect
      1. constructor
      2. attributeChangedCallback()
      3. connectedCallback()
4. React.Component - componentDidMount()

Unmount Phase

1. React.Component - componentWillUnmount()
2. React.Component - render()
   1. HTMLElement - disconnect 2. disconnectedCallback()

Upate Phase

1. React.Component - componentWillUpdate()
2. React.Component - render()
   1. HTMLElement - disconnect
      1. disconnectedCallback()
   2. HTMLElement - create/connect
      1. constructor
      2. attributeChangedCallback()
      3. connectedCallback()

Vue 2.x

• FYI: nesting a <div> within a <p> seems to break data binding in VueJS 2.5
  • (codepen example)
  • trying to track down the reason why this breaks
  • To be continued...

Resources

• Custom Elements Everywhere
• Bypass synthetic event system for Web Component events (facebook/react#7901)