However, if you'd like to simply extend a non-standard tag, you can always fall back to the element tag kind, which will extend HTMLElement, and represent the component through its retrieved name.

`js
// either as object
const Component = {
extends: 'element',
onconnected() { console.log(this.outerHTML); }
};

// or as class
class Component extends HTMLElement {
static get tagName() { return 'element'; }
onconnected() { console.log(this.outerHTML); }
};

const MyElement = heresy.define('MyElement', Component);
document.body.appendChild(MyElement.new());
// in console:
`

$3

While define(...) will use the global registry to define the specific declarative name, making it a good practice to namespace it (i.e. FWDatePicker, StencilForm etc.), it is possible to define local components through the usage of includes, also aliased as contains.

Such a list will still pass through the registry, so that local components are fully valid custom elements that never name-clash with anything else, so that it's easier to split complex components into various sub-modules and only define their main container globally.

The following example has been rewritten with extra details and is live on codepen.

`js
import {define, ref, render, html} from 'heresy';

import {User, Pass} from './form/ui.js';
import {validate, switchPage} from './form/utils.js';

const Form = {
extends: 'form',
includes: {User, Pass},
oninit() {
// refs can be declared upfront or inline (see render)
this.user = ref();
this.addEventListener('submit', this);
},
onsubmit(event) {
event.preventDefault();
if (validate(this.user.current, this.pass.current))
fetch('/log-in').then(switchPage).catch(console.error);
},
// render is invoked automatically on connected
// if no connected, or callback is explicitly defined
render() {
this.html
Your name:
Your pass:
;
}
};

define('SiteLogin', Form);
render(document.body, html);
`

The includes or contains property, if present, must be a map of "Name": Component pairs, where the name could also define the tag type, like it does with define(...).

In the previous example both User and Pass are components extending input, so that the tag name is not necessary, but {"User": User}, or {"User:button": User}, would eventually be valid as a local component.


#### How can components be local?
The main difference with local components is that their registry name gets polluted with a unique identifier, so that instead of the outcome would be . The unique identifier in between (xxx) is added in cases where a component can be defined or used together with many other components, so that name clashing won't ever be an issue.




$3

A similar example is live in Code Pen.

`js
import {define, html, render} from 'heresy';

// classes or objects, to define components, are the same
class MyButton extends HTMLButtonElement {

// (optional) static fields to define the component/class name or tag
// use define('MyButton:button', MyButton); if you want to avoid this
static get name() { return 'MyButton'; }
static get tagName() { return 'button'; }

// (optional) static callback to style components (once per definition)
// when there are local components, it will receive also these
// in definition order
static style(MyButton) {
// the component could be scoped so that
// to be sure the selector is the right one
// always use the received component to define its styles
return ${MyButton} {
border: 2px solid black;
}
}

// (optional) attributes that can either be true or false once accessed
// reflected on the DOM as either present, or not
static get booleanAttributes() { return ['checked']; }

// (optional) store any value directly and dispatch on${name} on changes
static get mappedAttributes() { return ['data']; }
// if ondata(event){} is defined, event.detail will have the new value

// (optional) native Custom Elements behavior with changes dispatched
// through the onattributechanged callback
static get observedAttributes() { return ['name', 'age']; }

// (optional) event driven initialization that will happen only once
// the ideal constructor substitute for any sort of one-off init
// this is triggered only once the component goes live, never before *
// * unless explicitly dispatched, of course
oninit(event) {}

// (optional) event driven lifecycle methods, added automatically when
// no Custom Elements native methods such as connectedCallback, and others
// have been explicitly set as methods
onconnected(event) {}
ondisconnected(event) {}
onattributechanged(event = {attributeName, oldValue, newValue}) {}

// (optional) populate this custom element content
// if the signature has at least one argument,
// as in render({useState, ...}),
// the render will be bound automatically
// with hooks capabilities
render() {
// this.html or this.svg are provided automatically
this.htmlClick ${this.props.name}!;
}

// (optional) automatically defined to trigger
// thison${event.type};
handleEvent(event) {}

// (optional) automatically defined to return this.getAttribute('is')
get is () {}
}

// components can be defined both as classes or objects
const Generic = {

// both name and extends are optional
// if defined via define('Name:extends', object)
name: 'Generic',
extends: 'element', // or div, p, etc

// statics are defined on the derived class
style(selector) {},
observedAttributes: [],
booleanAttributes: [],

// all other events supported too
oninit() {}
};

// define the custom element via class (requires static name and tagName)
define(MyButton);

// or define the custom element via Component:tag
define('MyButton

', MyButton);

// populate some node
render(document.body, html);

setTimeout(() => console.log(document.body.innerHTML));
//

Click Magic!
`

Compatibility

The test page uses and describes a few techniques to address all browsers, from IE9 to latest evergreen.

The following list describes the _heresy_'s compatibility break down:

IE9 and IE10 might* need an Object.freeze patch, to avoid breaking on frozen template literals when passed to polyfilled WeakMaps. The patch checks for the existence of WeakMap, hence it's completely safe for any modern browser, including IE11.
* old Edge and all IE might need a Custom Elements polyfill upfront. In this case the famous document-register-element would be the suggested choice, since it patches built-ins right away, too.
* Safari and WebKit have an understandable but pretty stubborn position regarding built-in elements, so that a 1K polyfill is needed in case you target Safari and WebKit.
* you don't need a polyfill for Safari if you only extend element, but you'll miss out 90% of the fun with programming through built-in extends

$3

`html



`

Alternatively, you can use this minified version to never download the Safari-only polyfill.

`html

`

Concept

Custom Elements built-ins are likely the best thing we have to build components the way we want to.

Instead of using a non standard indirection as JSX is, we can use the power of domtagger, the hyperHTML and lighterhtml tag engine, to replace once any with or without nested nodes.

The Custom Elements V1 API provides enough primitives to intercept any sort of attribute (i.e. the props in the example), but also react to events such connectedCallback or disconnectedCallback and attributeChangedCallback.

Mixed up with built-in extends in a way that any component is a real thing on the DOM instead of a facade of itself, _heresy_ makes the creation of apps, from simple to complex, a no-brainer: define the content through this.html or this.svg and that's it.

When any class is defined, it's not just necessarily a useless HTMLElement, it can be pretty much any kind of element.

The following example is live in Code Pen.
`js
import {define, ref, html, render} from 'heresy';

// a div
define(class Div extends HTMLDivElement {
static get name() { return 'Div'; }
static get tagName() { return 'div'; }
});

// a paragraph
define('P

', class extends HTMLParagraphElement {});

// a h1
define('H1

', class extends HTMLHeadingElement {});

// render them all + ref example
const refs = {};

// refs can be created right away
refs.div = ref();

// or within the render
render(document.body, html

Hello there

This is how custom elements look via heresy.

Isn't this awesome?

);

console.log(refs.h1.current); // the H1 instance/node
`




$3

You can see the following example live.
`js
// p.js - could be an object too
export default class extends HTMLParagraphElement {
static get tagName() { return 'p'; }
oninit() {
console.log(this.outerHTML);
}
};

// first.js - it has a local P
import P from './p.js';
export default {
extends: 'div',
includes: {P}, // with its own definition
render() {
this.html

first

// second.js - it uses P again as local
import P from './p.js';
export default {
extends: 'div',
includes: {P}, // with its own definition
render() {
this.html

second

const Div = define('Div', {
extends: 'div',
includes: {First, Second},
render() {
this.html;
}
});

// either
render(document.body, html