synergy-web-components

Synergy-web-components is a lightweight wrapper around the Synergy library, allowing you to create reusable Custom Elements with declarative templates and reactive data bindings using plain objects and factory functions.

Browser Support

Works in any modern browser that supports JavaScript Proxy.

Install

Using npm:

$ npm i synergy-web-components

Using unpkg CDN:

<script type="module">
  import define from 'https://unpkg.com/[email protected]';
</script>

Define

The define() function registers your Custom Element.

Syntax

define(tagName, factory, template);

Parameters

• tagName Name for the new custom element. Note that custom element names must contain a hyphen.

• factory A Factory function that returns a plain JavaScript object that will provide the data for your element.

• template (optional) Either an HTML string or a <template> element. If ommited, Elementary expects your document to include a Template element with an id matching tagName.

Example

<script type="module">
  import define from 'https://unpkg.com/[email protected]';

  let count = 0;

  const factory = ({ expanded = false, title, disabled = false }) => {
    return {
      id: `drawer-${count++}`,
      title,
      expanded,
      disabled,
      toggle() {
        this.expanded = !this.expanded;
      },
    };
  };

  factory.observedAttributes = ['expanded'];

  define('x-drawer', factory);
</script>
<template id="x-drawer">
  <style scoped>
    button {
      all: inherit;
    }
  </style>
  <h3>
    <button
      id="{{ id }}"
      disabled="{{ disabled }}"
      aria-expanded="{{ expanded }}"
      onclick="toggle"
    >
      {{ title }}
    </button>
  </h3>
  <div hidden="{{ !expanded }}" aria-labelledby="{{ id }}">
    <slot></slot>
  </div>
</template>

In the example above, we create a new x-drawer Custom Element that can be used anywhere on the page, like so...

<x-drawer title="foo"></x-drawer>

Factory Props

The elements initial attribute keys and values will be passed to your factory function during initialisation

Observed Attributes

Observed attributes can be declared directly on your factory function like so...

const factory = (props) => props;

factory.observedAttributes = ['name'];

Shadow Dom

SWC doesn't support Shadow DOM at the moment. This is to preserve the pre-rendering / hydration capabilities of Synergy. There are open proposals for the Web Platform that intend to make Shadow DOM declarative and serialisable. Until then, SWC provides a polyfill for Slots, as well as a limited CSS scoping mechanism.

Slots

Elementary doesn't support Shadow DOM, but it does polyfill (slots)[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot], so you can use these as per the spec to provide placeholders for custom markup.

Scoped CSS

Elementary provides lightweight, opt-in CSS scoping. Apply the scoped boolean attribute to a style tag within your Custom Elements template, and all of the selectors will be prefixed with an additional type selector and hoisted up into the document head, giving you one style tag shared between all instances. This effectively stops your Custom Element styles from leaking out into the document, but doesn't stop anything from sneaking in.