@heximal/element v0.1.5

Heximal Element

Heximal Element is a library for creating declarative custom elements - elements that are defined entirely in HTML.

Heximal Element provides a <h-define-element> element that defines new custom elements with reactivity, rich templates, scoped styles, and more.

Part of the Heximal project.

Example

<h-define-element name="simple-greeter" properties="name">
  <style type="adopted-css">
    :host {
      color: blue;
    }
  </style>
  <template>
    <h1>Hello {{ name }}!</h1>
  </template>
</h-define-element>

<simple-greeter name="World"></simple-greeter>

Element names

The custom element name is declared with the required attribute name. The name must include a dash (-) as per custom elements in the HTML specification.

Properties

Properties are specified with either the properties attribute or child <h-prop> elements.

The properties attribute takes a space-separated list of property names, all properties listed get an associated attribute of the same name, using the String type converter, with no reflection.

If you need to set property options like type, reflect, attribute

Example:

<h-define-element name="simple-greeter">
  <h-prop name="name" reflect type="String"></h-prop>
  <!-- ... -->
</h-define-element>

Styling

Styles are added with a <style type="adopted-css"> child element.

The type is "adopted-css" so that the styles do not apply to the document. The CSS text of the style element is added as an adopted stylesheet to the element's shadow root.

Note: Currently only a single <style> tag is supported. And while subclasses can override its base class's styles, there's no way to both add to and include the base class styles.

Template expressions

Template expressions are implicitly resolved against the element instance - there is no need to prefix property names with this.

Inheritance

A Heximal element can extend another Heximal element by referencing the base class with the extends attribute. The base class must come before the subclass in the HTML document.

The base class can define named template "blocks" that can be overridden by the subclass:

<h-define-element name="x-base">
  <template>
    <h1>Hello World</h1>
    <template name="block-1">Fallback content</template>
  </template>
</h-define-element>

<h-define-element name="x-foo" extends="x-base">
  <template>
    <template name="block-1">Override content</template>
  </template>
</h-define-element>

This type of sub-template has an implciit call to render the super template. If a subclass needs to add content around the superclass template, it can include an explicit call to the super template:

<h-define-element name="x-base">
  <template>
    <h1>Hello World</h1>
    <template name="block-1">Fallback content</template>
  </template>
</h-define-element>

<h-define-element name="x-foo" extends="x-base">
  <template>
    <div class="wrapper">
      Subclass content
      <template name="super">
        <template name="block-1">Override content</template>
      </template>
    </div>
  </template>
</h-define-element>