Issue 6487 - IOElement as base component for ABP UI

js/io-element.js

+/* globals module, require */
+
+"use strict";
+
+// Custom Elements ponyfill (a polyfill triggered on demand)
+const customElementsPonyfill = require("document-register-element/pony");
+if (typeof customElements !== "object")
+  customElementsPonyfill(window);
+
+// external dependencies
+const {default: HyperHTMLElement} = require("hyperhtml-element/cjs");
+
+// provides a unique-id suffix per each component
+let counter = 0;
+
+// common Custom Element class to extend
+class IOElement extends HyperHTMLElement
+{
+  // get a unique ID or, if null, set one and returns it
+  static getID(element)

[saroyanm, 2018/03/20 20:08:19]

Question: Why is the generation of unique ID is required ?
(I assume it's a HyperHTMLElement related question)

[a.giammarchi, 2018/03/21 07:27:19]

It's not, it's aria related question. Most of the aria helpers targets nodes by
ID. It's madness to find meaningful, unique, IDs per each `labelled-by` use case
and we already had discussions about the id-name when the only purpose of that
ID was to serve a11y.

Having a way to generate unique IDs when needed makes our life easier and
components content creation a no-brainer because you can always `<el
aria-labelled-by=${otherComponent.id}/>` and be sure there is one.

I hope I've answered your question.

[a.giammarchi, 2018/03/21 08:15:57]

I've forgotten an important detail. Once you have `<io-el>` with a unique id, it
is also easy/straight forward to recycle same ID internally while populating via
hyperHTML.

this.html`
  <input aria-labelled-by=${this.id + 'label'}>
  <label id=${this.id + 'label'}>hello</label>`;

This effectively make components both addressable and their own relevant parts
easy to retrieve too.

[saroyanm, 2018/03/21 11:22:21]

We could also wrap element inside of the label tag if we would like to make it
labeled, but I agree that having better flexibility to reference the element is
a good approach.

[saroyanm, 2018/03/21 11:22:22]

Noted.

+  {
+    return element.getAttribute("id") || IOElement.setID(element);
+  }
+
+  // set a unique ID to a generic element and returns the ID
+  static setID(element)
+  {
+    const id = `${element.nodeName.toLowerCase()}-${counter++}`;
+    element.setAttribute("id", id);
+    return id;
+  }
+
+  // lazily retrieve or define a custom element ID
+  get id()
+  {
+    return IOElement.getID(this);
+  }
+
+  // whenever an element is created, render its content once
+  created() { this.render(); }
+
+  // by default, render is a no-op
+  render() {}
+}
+
+// whenever an interpolation with ${{i18n: 'string-id'}} is found
+// transform such value into the expected content
+// example:
+//  render() {
+//    return this.html`<div>${{i18n:'about-abp'}}</div>`;
+//  }
+const {setElementText} = ext.i18n;
+IOElement.intent("i18n", id =>

[saroyanm, 2018/03/20 20:08:19]

What does intent do ? I couldn't find it in the documentation, maybe I've
overlooked ?

[a.giammarchi, 2018/03/21 07:27:19]

In HyperHTMLElement, being `define(...)` the method that actually defines the
class as Custom Element, the initial `hyperHTML.define(...)` is renamed
`.intent(...)`.

Documentation here: https://viperhtml.js.org/hyperhtml/documentation/#api-3

Please note that nobody has to use `intent`, unless really needed, because once
defined in here every parsing will consider interpolations with `{i18n:
'unique-id'}` objects as i18n content, effectively abandoning the class based
technique and putting text where it belongs: inside an element (at least
visually).

TL;DR this is a one off, that belongs to this root class only, to abstract away
i18n within every IOElement populated through hyperHTML.

[saroyanm, 2018/03/21 11:22:21]

Suggestion: Maybe we can document that somewhere, ex. in HyperHTMLElement README
?
Noted.

I still need to find time to go through the documentation.

[a.giammarchi, 2018/03/21 14:21:32]

Done.

+{
+  const fragment = document.createDocumentFragment();
+  setElementText(fragment, id);
+  return fragment;
+});
+
+module.exports = IOElement;