Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lamplightdev/compost
A collection of web component mixins
https://github.com/lamplightdev/compost
Last synced: about 2 months ago
JSON representation
A collection of web component mixins
- Host: GitHub
- URL: https://github.com/lamplightdev/compost
- Owner: lamplightdev
- License: mit
- Created: 2018-02-02T20:18:18.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2018-07-02T13:38:56.000Z (about 6 years ago)
- Last Synced: 2024-07-18T15:29:01.083Z (2 months ago)
- Language: JavaScript
- Size: 98.6 KB
- Stars: 19
- Watchers: 4
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# compost
> A collection of small Web Component mixins to add commonly required functionality without the bloat
- **No dependencies** - just mixin and go
- **Plain JavaScript** - no build tools required, compatible by default, debug in the browser with standard dev tools
- **No magic** - straight forward to understand
- **Small & efficient** - low overhead to keep your components lean
- **Include only what you need** - take it or leave it
- **Cross browser** - works on all modern browsers and IE11
Example Hacker News progressive web app - [https://github.com/lamplightdev/compost-hn](https://github.com/lamplightdev/compost-hn)
## Table of Contents
- [Install](#install)
- [Mixins](#mixins)
- [Usage](#usage)
- [Browser support](#browser-support)
- [Examples](#examples)
- [License](#license)
## Install
Install using [npm](https://npmjs.com):
```sh
npm install --save @lamplightdev/compost
```
## Mixins
### CompostShadowMixin
Adds a shadow DOM to your component. Takes a string returned from a `render()` method to set up the shadow DOM, and adds [ShadyCSS](https://github.com/webcomponents/shadycss) support if the polyfill is included for browsers that don't natively support shadow DOM. Also adds some convenience accessors for querying shadow DOM elements.
### CompostPropertiesMixin
Lets you specify your component's properties upfront, their types, whether their value should be reflected in an attribute, and an observer function to run when the property changes.
### CompostEventsMixin
Let's you add declarative event binding in your templates. Also adds some convenience methods for manual event binding and firing.
### CompostRepeatMixin
Experimental - Stamps out a template for each object in the `items` array property
### CompostMixin
A convenience mixin that includes `CompostShadowMixin`, `CompostPropertiesMixin`, and `CompostEventsMixin`:
```js
const CompostMixin = (parent) => {
return class extends
CompostEventsMixin(
CompostPropertiesMixin(
CompostShadowMixin(parent))) {}
};
```
### Where's the data binding?
There is none. For simple, well structured components you may not need data binding - turns out you can get a lot done with the standard DOM APIs (and it's the most efficient way to update the DOM too). But if data binding is your thing you can simply extend `CompostShadowBaseMixin` to include your data binding library of choice (I like [lit-html](https://github.com/Polymer/lit-html).)
## Usage
### CompostShadowMixin
```html
class App extends CompostShadowMixin(HTMLElement) {
render() {
return `
<style>
:host {
display: flex;
flex-direction: column;
max-width: 1280px;
margin: 0 auto;
}
</style>
<button class="button" id="buttonEat">Eat me</button>
<button class="button" id="buttonDrink">Drink me</button>
<button class="button" id="buttonClick">Click me</button>
`;
}
}
customElements.define('x-app', App);
```
Implement a `render` method that returns a string - your x-app component now has a shadow DOM with encapsulated CSS.
In addition the following convenience properties are added:
`this.$s` is a reference to the shadow DOM
`this.$` is equivalent to `app.shadowRoot.querySelector`
`this.$$` is equivalent to `app.shadowRoot.querySelectorAll`
`this.$id` is an object containing a mapping of all elements with their `id`
### CompostPropertiesMixin
```html
class App extends CompostPropertiesMixin(HTMLElement) {
static get properties() {
return {
siteUsername: {
type: String,
value: 'lovelace',
reflectToAttribute: true,
observer: 'observeSiteUsername',
},
};
}
observeUser(oldValue, newValue) {
console.log(oldValue, newValue);
}
}
```
Implement a static getter for `properties`, returning an object with the property name as the key, and the value an object containing:
|Key|Type|Default|Required|
|:--:|:--:|:--:|:--:|
|**`type`**|`{String\|Number\|Boolean\|Array\|Object}`|`String`|No|
|**`value`**|`{String\|Number\|Boolean\|Array\|Object\|null}`|`undefined`|No|
|**`reflectToAttribute`**|`{true\|false}`|`false`|No|
|**`observer`**|`{String}`|`undefined`|No|
`type`
The type of the property. Used when converting a property to an attribute, and vice-versa.
For boolean properties, `true` is converted to an empty attribute, while `false` removes the attribute. The presence of an attribute sets the property to `true`.
For array and object properties, the property is JSON stringified (`JSON.stringify`) when converting to an attribute, and JSON parsed (`JSON.parse`) when converting to a property.
`value`
The default value of the property if the property has not been initialised from an attribute, or the property was not set before the element was added to the DOM. If an attribute with a name matching the property name (converted to kebab-case) is present on the element this will always override the default.
`reflectToAttribute`
Whether the property should be reflected to an attribute with the same name. Camel cased property names (e.g. `siteUsername`) are converted to kebab cased attribute names (e.g. `site-username`) automatically.
`observer`
If defined, this is the name of a method in your class that will be called when the property changes with arguments containing the previous and new values. Strict equality is used when comparing old and new values, so changes in object sub properties or array elements won't trigger an observer - use of immutable data is advised.
The observer will also be called on initialisation - either from a matching attribute or a default `value`.
Observer calls are batched and dispatched asynchronously. This means that when the observers are called all properties will have their most recent values - so the order in which the observers are called should not be important.
### CompostEventsMixin
```html
class App extends CompostEventsMixin(CompostShadowMixin(HTMLElement)) {
render() {
return `
<button on-click="test">Click me</button>
`;
}
test(event) {
console.log(this, event);
}
}
customElements.define('x-app', App);
```
Any attribute beginning `on-{eventName}` (where eventName is one of [these standard DOM events](https://github.com/lamplightdev/compost/blob/86a15dd693112e6a6433a6262270f29a0869b5a3/src/events-mixin.js#L4)) will bind that event to the method specified in the attribute value (`test` in the example above.) The method is automatically bound to the current class, so `this` in the method will always refer to the class itself.
Event listeners are added in `connectedCallback` and removed in `disconnectedCallback`.
In addition the following convenience methods are added:
`this.on(el, type, func)` is equivalent to `el.addEventListener(type, func)`
`this.off(el, type, func)` is equivalent to `el.removeEventListener(type, func)`
`this.fire(type, detail, bubbles = true, composed = true)` is equivalent to
```js
this.dispatchEvent(new CustomEvent(type, {
bubbles,
composed,
detail,
}));
```
### CompostRepeatMixin
```html
class App extends CompostRepeatMixin(CompostShadowMixin(HTMLElement)) {
render() {
return super.render(`
<h1>Repeater<h1>
`);
}
getTemplateString(value, index) {
return `
<button></button>
`;
}
getKey(value, index) {
return value;
}
updateItem(el, value, index) {
el.textContent = value;
}
}
customElements.define('x-app', App);
const app = document.querySelector('x-app');
app.items = ['one', 'two', 'three'];
```
The call to `render` returns a template string for anything that needs to appear above the repeated template and will be added to the element's shadow DOM. The call to `getTemplateString` returns a template string that contains the DOM that needs to be repeated and is combined with the `items` array property to stamp out new elements in the light DOM. So the above will output a custom element with `
Repeater
` in the shadow DOM, and the following in a `slot`:
```html
one
two
three
```
`this.getKey(value, index)` must return a unique key for each `value` in `items` so that items can be efficiently added/removed/reordered when the items array changes.
`updateItem(el, value, index)` is used to update the repeated element when the `value` in `items[index]` changes.
## Browser support
Works with no polyfills or build step for browsers that support ES2015, Shadow DOM v1, Custom Elements v1 and HTML Templates. This is currently the latest versions of Chrome and Safari.
Works with other browsers down to IE11 when using the [web components polyfills](https://github.com/WebComponents/webcomponentsjs) and a transpilation step (e.g. Babel) as needed.
## Examples
[HackerNew Progressive Web App](https://github.com/lamplightdev/compost-hn) - built using compost
Coming soon - an example using lit-html.
Coming soon - an example that works on all browsers down to IE11.
## License
[MIT License](https://oss.ninja/mit/lamplightdev) © [Chris Haynes](https://lamplightdev.com)