devpunks / snuggsi

snuggsi ツ - Easy Custom Elements in ~1kB
https://snuggsi.com
MIT License
398 stars 17 forks source link
custom-elements dom ecmascript es6 frontend html javascript template-literals webcomponents

snuggsi ツ - Easy Custom Elements in ~1kiloByte

NPM monthly downloads Travis CI build Brotli size npm version dependency status license Pull requests welcome!

All you need is a browser and basic understanding of HTML, CSS, & JavaScript Classes to be productive!

Performance is the art of avoiding work - #FreeJewelry 💍 💎

# Navigation - [Why ?](#why-) - [Easy Installation](#easy-installation) - [Browser Support](#browser-support) - [Quick Tour](#quick-tour) - [<`custom-elements`>](#custom-elements) - [`HTML` Declaration](#html-declaration) - [`Element` Definition](#element-definition) - [`class` Description](#class-description) - [`Template`](#template) # [Why ?](https://github.com/devpunks/snuggsi/wiki/Why%3F) 1. You prefer to be [D.R.Y.](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) and build reusable web components on a gradual learning curve. 2. Because [You _(probably)_ don't need a JavaScript Framework](https://dev.to/steelvoltage/you-probably-don-t-need-a-front-end-framework-26o6). 3. You prefer [convention over configuration](https://en.wikipedia.org/wiki/Convention_over_configuration). 4. [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components) are [ready](https://twitter.com/domenic/status/904114041752358913) for [production](https://twitter.com/WebReflection/status/761316429559922688) & [Custom Elements v1](https://www.w3.org/TR/custom-elements) has [support for every modern 🍃 greenfield browser](#browser-support). # Easy Installation Made with [💖 Vanilla JS™](http://vanilla-js.com) No need to learn Node.js, React, Webpack, Babel, or Gulp. _(You can if ya **want** to use **snuggsiツ** with those tools. But you don't **need** to!)_ __*#UseThePlatform*__ **snuggsiツ** works in a plain 'ol HTML file! Simply place the following **<script>** within your webpage: ```html ``` Et Voila _(that's it!)_ ツ # Browser Support _**snuggsiツ** provides a [prolyfill](https://github.com/devpunks/snuggsi/wiki/What-is-a-ProlyFill) for the following native web platform features:_ | Support | Edge* | Chrome* | Firefox* | Safari 9+ | Android* | iOS Safari* | |:----------:|:-----:|:-------:|:--------:|:---------:|:--------:|:--------------:| | [Templates](#templates) |✅ |✅ |✅ |✅ |✅ |✅ | | [Custom Elements](#custom-elements) |✅ |✅ |✅ |✅ |✅ |✅ | | Slot Replacement |✅ |✅ |✅ |✅ |✅ |✅ | _\*Indicates the current version of the browser_ # Quick Tour **snuggsiツ** encourages [convention over configuration](https://en.wikipedia.org/wiki/Convention_over_configuration) using familiar techniques that are native to all browsers. Gone are the sleepless nights where your code [suffers from `
`itus](https://css-tricks.com/css-beginner-mistakes-1/), or need to install packages on a terminal just to write `HTML`. **People who are more comfortable with `HTML` should be able to start marking up their ideas immediately!** You shouldn't have to know CSS or JavaScript! _(But it definitely helps if you need styling and functionality)_. **snuggsiツ** believes in using [Progressive Enhancement](https://en.wikipedia.org/wiki/Progressive_enhancement). Not just with your code, but also with your Developer eXperience _(DX)_. We will start from the beginning with a simple Custom Element and gradually enhance functionality step-by-step. ## [<`custom-elements`>](/element#readme) When picking a name for your custom element [there are a few naming conventions](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name) you must be aware of. We can simply use `hello-world` for now. ### `HTML` Declaration `HTML` has always been a declarative language. Why not just use it to declare Custom Elements? If you know [how to write `HTML`](https://developer.mozilla.org/en-US/docs/Web/HTML) you can start using **snuggsiツ**. Sometimes you need to sandbox a section of your page for styling. Other times you need a custom container of complex functionality. Either way you usually start with a plain ole' `HTML` element declaration: #### A Brief History Lesson _Not all HTML tags are created equal!_ A _"valid `HTML` Element"_ has always _allowed_ non-standard tag names _(as long as you remember to provide a closing tag)_. In the bad old days of the web, [`HTML5` elements were once _"non-standard"_ to `HTML 4.0`](https://johnresig.com/blog/html5-shiv). However, these days we have far more flexibility in our markup: ```html


``` 👍 Rule of thumb: _Close all **non-standard** `HTML` Element tags!_
As you learned earlier there are a few conventions to adhere to be considered a _"valid **Custom** Element"_ you will need an alpha-numeric character followed by a hyphen in the tag name _(at minimum)_: ```html ``` 👍 Rule of thumb: _Use [kebab case (with hyphens)](https://en.wiktionary.org/wiki/kebab_case) for tag names._
We now know enough to be dangerous and make your own Custom Element tag: ```html ``` Et Voila ツ _(No really … That's it!)_
At this point your **custom** element can be styled using CSS just like any other element. ```html Hello ``` See [A JavaScript-free custom element implementation](https://www.stefanjudis.com/notes/a-javascript-free-custom-element-implementation/) And [Building a `` component](https://web.dev/building-a-tooltip-component/) for more _(sans JavaScript)_ custom elements CSS fun!
#### Live `{token}` Declarations The `{token}` is simply a [well named dynamic variable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Variables) you will **Describe** later. `{token}`s are placeholders which watch for changes to your custom element's `class` property of the same name. Since they are _"placeholders"_ and not live code, Front-end designers are no longer blocked by needing to install a JavaScript framework just to write `CSS`! ```html This is a token 👉 {baz} and {bat} is another! ``` 👍 Rule of thumb: _If the `{token}` name is [not in a thesaurus](https://en.wikipedia.org/wiki/Metasyntactic_variable) then I probably shouldn't use it._
A _"live token"_ is a declarative way to bind data values to your Custom Element. A nice convention to a real historical P.I.T.A. of keeping values updated. Live `{token}`s are also _"✨ automagically"_ updated each time the element re-renders. Let's add a `{token}` to ``: ```html Hello {planet} ``` 👍 Rule of thumb: _A `{token}` is not _"live"_ until there is a `class` description for its functionality._
Lastly, we can visually enhance your `` Custom Element by making it [_"block level"_](https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements) with CSS `display: block`. This way your element plays nicely in your layout: ```html Hello {planet} ``` We have finished your Custom Element **Declaration** using `HTML`, & `CSS`!🌟 Now on to your **Definition**.
### `Element` Definition Every Custom `Element` **MUST** be [_Defined_ within the `CustomElementsRegistry`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry). This is simple with **snuggsiツ** Let's `define` your element using the `Element` interface: ```javascript // Element `hello-world` ``` 👍 Rule of thumb: _Use backticks around tag names (``)._ This syntax is not JSX. It's actually called [tagged template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates) and is native to the platform. Custom elements use the native `Element` interface definition strategy for two reasons: 1. To prevent you from worrying about browser inconsistencies as the technology matures. 2. Prevent global namespace pollution. _([`Element` has been native to the web platform for decades!](https://developer.mozilla.org/en-US/docs/Web/API/Element))_ Classic JavaScript syntax may also be used. However [this should be the job of a transpiler not the developer](https://en.wikipedia.org/wiki/Source-to-source_compiler). Transpilers take care of [normalizing Modern JavaScript to a specific retrograde](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Cross_browser_testing/JavaScript). ```javascript Element ('hello-world') // classic javascript definition ```
### `class` Description Great so far!🎉 Although your Element behaves like any other `HTMLElement`, we should add some functionality custom to your needs. Next, we need to pass a `class` description to the function returned by your `Element` definition. ```javascript // Element `hello-world` ( class HelloWorld extends HTMLElement { … } ) ``` 👍 Rule of thumb: _**MUST** define [a `class` which `extends HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)_ Let's shorten your description up a bit by using an [anonymous class expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/class) to describe the `class`. This convention is preferred as using an [explicit `class` declaration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/class) name can potentially pollute the global namespace: ```javascript // Element `hello-world` ( class extends HTMLElement { … } ) ``` 👍 Rule of thumb: _Use enclosing parenthesis around `(class …)` definitions._
#### Live `{token}` Definitions Since we [previously declared a `{planet}` token](#live-tokens) within your `` element we need to also define a `class property` **of the same name** to replace the `{planet}` token with a value. Class properties may look like typical JavaScript Functions. However, they are treated as properties. _(called without parenthesis)_. `class` properties are described by using the [`get`ter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get) and [`set`ter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set) annotations before the name. Let's add a property to your `class` definition and give `{planet}` some life: ```javascript // … {planet} … Element `hello-world` (class extends HTMLElement { get planet () // used for {planet} token // "✨ automagic" token binding { return 'world 🌎' } }) ``` 👍 Rule of thumb: _`class` properties are functions begining with the keywords `get` & `set`._ 👍 Rule of thumb: _`{tokens}` will use the `class` property value of the same name by default._ ⚠️ The Live `{token}` value is updated after each re-render but it beyond the scope of this simple example. Since your `hello-world` Custom Element is an `HTMLElement` at its core, we can access your property directly from the DOM! ```javascript // document.querySelector ('hello-world').planet // world 🌎 ``` 👍 Rule of thumb: _Do not use parenthesis `()` when calling `get`ters & `set`ters._
#### Global `event` Listeners `event` handlers can be any method function which can be placed on any child elements and also onto the custom element itself _(i.e.`onclick=eatBacon`)_. However, you will not have to explicitly set the handler in HTML when you follow native naming conventions. This is the magic behind **snuggsiツ** Global `event` Listeners. They register themselves onto the custom element and _"listen"_ for you! As a convenience, your new custom element uses [Event Delegation](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events#Event_delegation) to capture all its children's [event bubbles of the same name](https://javascript.info/bubbling-and-capturing). ```javascript // // `onclick` is "automagically" attached // // ACHOO! // Element `hello-world` (class extends HTMLElement { // native event handler names // are "✨automagically" attached to `hello-world` onclick (event) { // prevent event from bubbling // Custom Element will re-render // after event unless prevented event.preventDefault () event.target // element which triggered event this // is ALWAYS bound to the Custom Element container 🎉 } onsneeze (event) { /* must be declared in HTML
```
### Hello Kitty! _(advanced)_ [Play `` Demo](https://jsfiddle.net/yLdatmvz) _…or just copy & 🍝pasta into a new HTML file and have at it!_ ```html
{greeting}
Random kitty cat
``` ## [`Template`](/html-template-element#readme) The `