@wesib/wesib v2.0.2

Wesib: Web Components Building Blocks

Wesib is a base for web components definition.

It provides a way to define custom elements. But instead of extending HTMLElement, it supports arbitrary component classes, and defines custom elements for them programmatically.

Wesib provides an IoC container, a component definition and lifecycle callbacks, and an infrastructure for opt-in features that can involve in component definition process and thus alter the resulting components in very flexible way.

This package provides a core API.

The @wesib/generic package provides generic web components and features.

The examples can be found in @wesib/examples.

Components

Wesib allows defining custom element by decorating a component class with @Component decorator:

import { Component } from '@wesib/wesib';

@Component('my-component') // Custom element name
export class MyComponent {
  // ...component definition
}

No need to extend HTMLElement or any other class. Instead, Wesib creates a custom element accordingly to its definition built either programmatically or using component decorators.

To register custom component(s) call bootstrapComponents() function like this:

import { bootstrapComponents } from '@wesib/wesib';

bootstrapComponents(MyComponent);

After that the custom element can be used anywhere in the document:

<my-component></my-component>

The component instance created along with a custom element and bound to it. All the logic of custom element delegated to the bound component instance.

Element Attributes

To define custom element attributes use @Attribute or @AttributeChanged component property decorators, or @Attributes component class decorator.

import { Attribute, AttributeChanged, Attributes, Component } from '@wesib/wesib';

@Component('my-component') // Custom element name
@Attributes('attribute-one', 'another-attribute')
export class MyComponent {
  @Attribute('attribute-two') // Attribute name. When omitted the property name is used
  attribute2!: string | null; // Attribute value is accessed instead.

  @AttributeChanged('attribute-three') // Attribute name. When omitted the method name is used
  setAttribute3(newValue: string, oldValue: string | null) {
    // This is called on attribute value modification with new and old values
  }
}

<my-component
    attribute-one="1"  <!-- Can be accessed with element's `element.getAttribute("attribute-one")` -->
    attribute-two="2"  <!-- Can be accessed as `attribute2` property of `MyComponent` -->
    attribute-three"3" <!-- Triggers `setAttribute3()` method call -->
></my-component>

Element Properties

To define the properties of custom element use a @DomProperty component property decorator.

import { Component, DomProperty } from '@wesib/wesib';

@Component('my-component') // Custom element name
export class MyComponent {
  @DomProperty('elementProperty') // Element property name. The decorated property name is used if omitted.
  customProperty = 12; // Element's `elementProperty` is backed by this one.
}

The same can be done for element methods with @DomMethod decorator, which is just a convenient alias for @DomProperty.

IoC Container

Wesib provides contexts for each component and feature (see below). This context can be used to access provided values.

For example, each component class constructor accepts a ComponentContext instance as its only argument.

import { Component, ComponentContext } from '@wesib/wesib';

@Component('my-component') // Custom element name
export class MyComponent {
  private readonly _service: MyService;

  constructor(context: ComponentContext) {
    this._service = context.get(MyService); // Obtain a `MyService` instance provided by some feature elsewhere.
  }
}

IoC container implementation is based on @proc7ts/context-values.

Features

Apart from custom elements definition and IoC container, everything in Wesib is an opt-in feature.

It is possible to define custom features to extend Wesib. E.g. to define or augment existing components, extend custom elements (like @Attribute or @DomProperty decorators do), or provide some context values.

The feature is a class decorated with @Feature decorator:

import { cxBuildAsset } from '@proc7ts/context-builder';
import { ComponentContext, DefinitionContext, Feature, FeatureContext, FeatureSetup } from '@wesib/wesib';

@Feature({
  needs: [
    OtherFeature1, // Requires other features to be enabled.
    MyComponent, // The required component will be defined too.
  ],
  setup(setup: FeatureSetup) {
    setup.provide(
      cxBuildAsset(
        GlobalService, // Provide a `GlobalService` available globally
        () => new GlobalService(), // in all IoC contexts
      ),
    );
    setup.perDefinition(
      cxBuildAsset(DefinitionService, ({ context: definitionContext }) => {
        // Provide a `DefinitionService` available during component definition.
        // Such service will be provided per component class
        // and will be available during custom element construction,
        // e.g. to `onDefinition()` listeners.
        return new DefinitionService(definitionContext);
      }),
    );
    setup.perComponent(
      cxBuildAsset(MyService, ({ context: componentContext }) => {
        // Provide a `MyService` available to components.
        // Such service will be provided per component instance
        // and will be available to component instance and `onComponent()` listeners.
        return new MyService(componentContext.component);
      }),
    );
  },
  init(context: FeatureContext) {
    // Bootstrap the feature by calling methods of provided context.

    context.onDefinition((definitionContext: DefinitionContext) => {
      // Notified on each component definition.

      // The service provided with `perDefinition()` method above is available here
      const definitionService = definitionContext.get(DefinitionService);

      definitionContext.whenReady(() => {
        // This is called when element class is defined.
        console.log(
          `Define element class ${definitionContext.elementType.name}` +
            ` for component of ${definitionContext.componentType.name} type`,
        );
      });
    });
    context.onComponent((componentContext: ComponentContext) => {
      // Notified on each component instantiation.

      // The service provided with `perComponent()` method above is available here
      const myService = componentContext.get(MyService);

      componentContext.whenReady(() => {
        // This is called when component is instantiated,
        // which happens right after custom element instantiation.
        console.log(componentContext.element, ` is instantiated for`, componentContext.component);
      });
    });
  },
})
export class MyFeature {}

To enable a custom feature just pass it to bootstrapComponents() like this:

import { bootstrapComponents } from '@wesib/wesib';

bootstrapComponents(MyFeature);

Note that components are kind of features that, when passed to this function (or enabled with needs option), register themselves as components.

Component State

Whenever a component state changes, e.g. when element attribute or property value changes, a state update notification issued.

A state update notification can also be issued by calling a ComponentContext.updateState() method:

import { Component, ComponentContext } from '@wesib/wesib';

@Component('my-component') // Custom element name
export class MyComponent {
  data: any;

  constructor(private readonly _context: ComponentContext) {}

  async loadData() {
    const newData = await fetch('/api/data').then(response => response.json());
    const oldData = this.data;

    this.data = newData;
    this._context.updateState('data', newData, oldData); // Update the state
  }
}

A ComponentState instance available in component context allows to track the component state updates.

Shadow DOM

It is possible to attach shadow root to custom element by decorating the component with @AttachShadow decorator.

If shadow DOM is supported, then a shadow root will be attached to element. Otherwise, an element itself will be used as shadow root. In both cases the shadow root will be available in component context under [ShadowContentRoot] key.

A ComponentContext.contentRoot property is always available. It either contains a shadow root, or element itself. This is a root DOM node component element contents.

Rendering

Wesib core does not provide any mechanics for component rendering. It is completely up to the developer which rendering mechanics to use: direct DOM manipulations, template processing, virtual DOM, etc.

However, Wesib is able to notify the renderer on component state updates and trigger its rendering. For that a @Render decorator can be applied to component renderer method:

import { Attribute, Component, ComponentContext, Render } from '@wesib/wesib';

@Component('greet-text')
export class GreetTextComponent {
  @Attribute()
  name: string | null;

  constructor(private readonly _context: ComponentContext) {}

  @Render()
  render() {
    this._context.contentRoot.innerText = `Hello, ${this.name}!`;
  }
}

The @Render-decorated method will be called from requestAnimationFrame() callback by default. So, it won't be called too frequently.