Core Concepts

Elements (this.els / this.externalEls)

Rather than scattering querySelector calls (and brittle class/ID selectors) throughout a component, BAOCustomElement resolves children via data attributes derived from the element's own identifier.

• this.els finds elements inside the component, marked with data-<identifier>-el.
• this.externalEls finds elements anywhere in the document, marked with data-<identifier>-external-el.

<product-form>
  <button data-product-form-el="submit">Add to cart</button>
</product-form>

class ProductForm extends window.BAO.CustomElement() {
  setupListeners () {
    // this.els.submit.element -> the <button>
    this.listeners.add(this.els.submit.element, 'click', this.onSubmit)
  }
}

Each resolved entry is an El object:

Property	Type	Description
exists	boolean	Whether at least one matching element was found
elements	HTMLElement[]	All matching elements
element	HTMLElement	The first matching element
selector	string	The attribute selector used to find them

Listeners

Every instance is given a Listeners manager on this.listeners. Bind events through it in setupListeners(), and they are automatically torn down in disconnectedCallback() — no leaked handlers when an element is removed from the DOM (for example when a section is re-rendered).

Validation

Declaring required markup as static getters causes the element to validate itself on construction and throw a descriptive error if anything is missing. This surfaces integration mistakes immediately rather than as silent undefined failures later.