<title>snuggsiツ</title>

<meta charset=utf-8>

name=viewport

content=user-scalable=no,initial-scale=1.0,minimum-scale=1.0,maximum-scale=1.0,width=device-width,height=device-height

<link rel=icon href=/favicon.ico >

as=style

href=index.css

rel='preload stylesheet'

// enough inline styles to paint to fold

// Japanese colors - https://en.wikipedia.org/wiki/Traditional_colors_of_Japan#Red.2FViolet_series

<github-ribbon style=display:none

url=https://github.com/devpunks/snuggsi>

<header-group style=text-align:center;padding-top:1em;display:block>

<h2>

<a href=//snuggsi.com title=snuggsiツ style=color:white>snuggsiツ</a>

<br>

<small>Easy Custom Elements in

<a

target=github

href=https://github.com/devpunks/snuggsi/tree/master/dist#readme>

~ 1<abbr title=kiloByte>kB</abbr>

</a>

</small>

</h2>

<section slot=subheader id=badges style=display:none >

<a href=https://npmjs.org/package/snuggsi>

<img alt='NPM monthly downloads' src=https://img.shields.io/npm/dm/snuggsi.svg?style=flat>

</a>

<a href=//github.com/devpunks/snuggsi/tree/master/dist#readme>

<img alt='Brotli size' src=https://img.shields.io/badge/Brotli%20size:-~%201kB-ff69b4.svg>

</a>

<a href=//www.npmjs.com/package/snuggsi>

<img alt='npm version' src=//img.shields.io/npm/v/snuggsi.svg>

</a>

<a href=//david-dm.org/devpunks/snuggsi target=external>

<img alt='dependency status' src=//david-dm.org/devpunks/snuggsi/status.svg>

</a>

<a href=//github.com/devpunks/snuggsi/blob/master/LICENSE.txt target=external>

<img alt=license src=//img.shields.io/npm/l/snuggsi.svg>

</a>

<a href=//github.com/devpunks/snuggsi/issues target=external>

<img alt='Pull requests welcome!' src=//img.shields.io/badge/PRs-welcome-brightgreen.svg>

</a>

</section>

<!-- https://vuejs.org/v2/guide -->

<!-- http://aurelia.io/consulting.html -->

<!-- https://skatejs.gitbooks.io/skatejs/content -->

<header>Getting Started</header>

<ul>

<li>

<a href=/examples/hello-world >&lt;hello-world&gt;</a>

<li>

<details>

<summary><a href=#installation>Installation</a></summary>

<ul>

<li>

<a href=#>Files Organization</a>

<!-- https://medium.com/styled-components/component-folder-pattern-ee42df37ec68 -->

<li hidden >

<a href=#><code>&lt;script&gt;</code> tag</a>

<li hidden >

<a href=#>Chrome Extension</a>

<!-- https://github.com/pakastin/redom-devtools/blob/master/dist/devtools.js -->

<li hidden >

<a href=#><code>$ npm i snuggsi</code></a>

</details>

<li>

<details>

<summary><a href=#lifecycle >Lifecycle</a></summary>

<ol>

<li>

<a href=#lifecyle:definition >Definition</a>

<li>

<a href=#lifecyle:construction >Construction</a>

<li>

<a href=#lifecyle:reflection >Reflection</a>

<li>

<a href=#lifecyle:imports >Imports</a>

<!-- This is a bit wonky in nomenclature and semantics -->

<li>

<a href=#lifecyle:slots >Slot Replacement</a>

<li>

<a href=#lifecyle:rendering >Rendering</a>

<ol>

<li>

<a href=#lifecycle:rendering:tokens >Tokens</a>

<li>

<a href=#lifecycle:rendering:templates >Templates</a>

<li>

<a href=#lifecycle:rendering:registration >Event Registration</a>

</ol>

<li>

<a href=#lifecyle:idle >Idle</a>

<li>

<a href=#lifecyle:events >Handling Events</a>

</details>

<li>

<details>

<summary><a href=#conventions >Conventions</a></summary>

<ul>

<li>

<a href=#tokens >Tokens</a>

<li>

<!-- http://blog.aurelia.io/2016/05/23/aurelia-shadow-dom-v1-slots-prerelease -->

<a href=#slots >Slots</a>

<li>

<a title=Context href=#context >Context</a>

<li>

<a title=Mixins href=#mixins >Mixins</a>

</details>

<li>

<details>

<summary><a href=#practices>Best Practices</a></summary>

<ul>

<li></li>

</details>

<li>

<details>

<summary><a href=#antipatterns>Anti-Patterns</a></summary>

<ul>

<li>Javascript Attributes</li>

<!-- No javascript in `<link>` elements (think <LINK> headers -->

</details>

</ul>

<header>Documentation</header>

<ul>

<li>

<details>

<summary><a href=#interfaces>Interfaces</a></summary>

<ul>

<li>

<details>

<summary><a href=#interfaces:element>Element</a></summary>

<ul>

<li>

<a href=#interfaces:element:select>.select</a>

<li>

<a href=#interfaces:element:selectAll>.selectAll</a>

</details>

<li>

<a href=#interfaces:template>Template</a>

</details>

<li>

<details>

<summary><a href=#events>Events</a></summary>

<ul>

<li>

<a href=#events:connect><em>(on)</em>connect</a>

<li>

<a href=#events:idle><em>(on)</em>idle</a>

<li>

<a

rel=external

target=external

href=https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers>Native Handlers</a>

</ul>

<footer>

<ul>

<li>

<a

rel=help

target=wikipedia

href=https://en.wikipedia.org/wiki/DOM_events#Inline_model >

Inline Registration

</a>

</ul>

</footer>

</details>

</ul>

</footer>

</details>

<li>

<details>

<summary><a href=#mixins>Mixins</a></summary>

<footer>

<ul>

<li>

<a

target=mdn

rel=external

href=https://developer.mozilla.org/en-US/docs/Glossary/Mixin>

<abbr title='Mozilla Developer Network'>MDN</abbr>

Mixins

</a>

<li>

<a

rel=external

target=wikipedia

href=https://en.wikipedia.org/wiki/Mixin>

Wikipedia Mixins

</a>

<li>

<a

target=mdn

rel=external

href=https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#Mix-ins>

ECMAScript Mixins

</a>

</ul>

</footer>

</details>

<li>

<details>

<summary><a href=#modules>Modules</a></summary>

<ul>

<li>

<a href=#modules:html><abbr title='Hyper-Text Markup Language'>HTML</abbr> Modules</a>

<li>

<a href=#modules:ecmascript>ECMAScript Modules</a>

</ul>

<footer>

<ul>

<li>

<a rel=external target=external href=https://aremodulesready.com>Are Modules Ready?</a>

</ul>

</footer>

</details>

<li>

<details>

<summary><a href=#imports>Preloads</a></summary>

<!-- meta tags -->

<!-- link rel=preload/prefetch -->

<!-- HTML5 The road to link relations -->

<!-- https://en.wikipedia.org/wiki/Link_relation -->

<!-- resource hints https://w3c.github.io/resource-hints/ -->

<!-- link types - https://html.spec.whatwg.org/multipage/links.html#linkTypes -->

<footer>

<ul>

<li>

<a

target=ietf

rel=external

title='View Web Linking on IETF'

href=https://tools.ietf.org/html/rfc5988>

<abbr title='Internet Engineering Task Force'>IETF</abbr>

Web Linking

</a>

<li>

<a

rel=external

target=whatwg

title='View Link Relations on WHATWG'

href=https://blog.whatwg.org/the-road-to-html-5-link-relations>

<abbr title='Web Hypertext Application Technology Working Group'>WHATWG</abbr>

Link Relations

</a>

<li>

<a

target=mdn

rel=external

title='View Preloading Content on MDN'

href=https://developer.mozilla.org/en-US/docs/Web/HTML/Preloading_content>

<abbr title='MDN'>MDN</abbr>

Preloading Content

</a>

</footer>

</details>

</ul>

<main role=main>

<section view id=installation>

<h1>Easy Installation</h1>

<p>No need for Node.js, Webpack, Babel, or Gulp.

<p><strong>snuggsiツ</strong> works in production or in a plain 'ol HTML file!

<p>Simply place the following script within your webpage:</p>

<pre><code>

<em class=comment>&lt;!-- http(s): protocol required to run locally --&gt;</em>

&lt;script nomodule src=//unpkg.com/snuggsi&gt;&lt;/script&gt;

</pre></code>

<p class=center>Et Voila <em>(that's it!)</em> ツ

<p class=center>See

<a target=github href=https://github.com/devpunks/snuggsi/wiki/Module-Imports>ECMAScript Module Imports</a>

for<code> &lt;script type=module&gt;</code> support!

<section view id=lifecycle>

<h1>Custom Element Lifecycle</h1>

<dl>

<dt id=lifecycle:definition >0. <code>define</code> Element

<dd>

A custom element is <em>"defined"</em> by specifying the <code>Element `your-tag-name`</code>

declaration immediately followed with a <code>(class extends HTMLElement {})</code> definition.

The custom element will be considered an <code>UnknownHTMLElement</code> until an <code>Element</code>

definition is specified. This means your custom element can be styled like any other HTML element.

However, your element will not have functionality until after definition.

<dt id=lifecycle:construction >1. <code>initialize</code> Construction

<dd>

After <strong>Definition & Declaration</strong> the custom element will go through

it's <code>constructor ()</code> routine. Typically you will not need to define a

<code>constructor ()</code> on your <code>class</code>. <strong>snuggsiツ</strong>

takes care of all <code>super ()</code> calls for you on instantiation.

<br><br>

If you would like to alter the custom element construction,

define an <code>initialize ()</code> function which is a hook that will be used automatically.

<dt id=lifecycle:reflection >2. Reflection

<dd>

After <strong>Construction</strong> the custom element will inspect your

<code>class extends HTMLElement</code> definition for Event Handlers.

These are typically methods prefixed with <em><strong>on</strong> (example: <code>onclick (event)</code>)</em>.

<strong>snuggsiツ</strong> will <em>automagically^&trade;</em>

delegate the event handler to your custom element container. As a

convenience the <code>this</code> keyword will <strong><em>Always</em></strong> be bound to the custom element.

<dt id=lifecycle:imports >3. <code>&lt;link&gt;</code>Importing

<dd>

The <code>&lt;link rel=import&gt;</code> step is critical for custom elements which contain a definition within an external file.

<em>(See <a

target=webcomponents

rel=external

href=https://www.webcomponents.org/community/articles/introduction-to-html-imports>

HTML Imports

</a> for more detail)</em>.

This is not your typical <em>"import javascript library"</em> you have been used to for years.

Imports are relative to the partial HTML document that contains the contents to hydrate each

instance of your custom element on upgrade.

<dt id=lifecycle:slots >4. <code>&lt;slot&gt;</code> Replacement

<dd>

After <strong>Importing</strong> the default contents of your custom element

there will be a replacement of any child elements with a

<code><a

target=mdn

rel=external

href=https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/slot>slot=slotname</a></code>

attribute within your custom element. Your <strong><em>"Named Slot Elements"</em></strong>

will replace the default import slots If the <em>slot</em> attribute coincides with

a <code><a target=mdn rel=external href=https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot>&lt;slot name=slotname&gt;</a></code>

defined within the imported custom element. In other words &hellip;

An element with a slot attribute is assigned to the slot created by the

&lt;slot&gt; element whose name attribute's value matches that slot attribute's value.

<dt id=lifecycle:rendering >5. Rendering

<dd>

Rendering of your custom element occurs on <strong>three specific occasions</strong>:

<ol>

<li>After <strong>on</strong> events <em>(example: <code>onclick (event)</code>)</em>.

<li>After initial <code>onconnect ()</code> hook is fired.

<li>Explicit calls to <code>this.render ()</code>.

</ol>

<em>(See <a

target=mdn

rel=external

href=https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame>

Animation Frames

</a> for more detail)</em>. Rendering can be disabled from within event handlers by calling <code>event.prevent ()</code>

from within handler functions. <strong>Be sure to declare <code>event</code> in your method signature.</strong>

<em>(example: <code>onclick (event) { event.prevent () }</code></em>

<dt id=lifecycle:rendering:tokens >5a. <code>{token}</code> Binding

<dd>

Occurs by <strong><em>"Tree Walking"^&trade;</em></strong>

child content of your custom element each time a <code>{token}</code> is discovered.

Tokens are a declarative placeholder for <strong><em>"Computed Property"</em></strong> values declared in your class definition.

<code>{foo}</code> is replaced with <code>"some value"</code> If a <code>get foo () { return 'some value' }</code>

is a property of your class definition.

<dt id=lifecycle:rendering:templates >5b. <code>&lt;template&gt;</code> Iteration

<dd>

Often we need to iterate over collections within a custom element. Traditionally this is done

<a

target=external

rel=external

href=https://tylermcginnis.com/imperative-vs-declarative-programming/>imperatively vs. declaratively</a>

by using looping mechanisms that feel more like leaky abstractions than common HTML. <strong>snuggsiツ</strong>

will <strong><em>"Tree Walk"^&trade;</em></strong> the children of your custom element looking for

<code>&lt;template name=&hellip;&gt;</code> and <em>"bind"</em> the collection value of a property with the same name on your class.

<dt id=lifecycle:rendering:registration >5c. Event Registration

<dd>

One of the many pains of classic browser programming is registering events on DOM elements.

<strong>Event Registration</strong> is the process of declaratively registering event handlers by name

within your custom element and <code>&lt;template&gt;</code> HTML.

<strong>snuggsiツ</strong> will <strong><em>"Tree Walk"^&trade;</em></strong>

your custom element and children looking for

<a

rel=help

target=mdn

href=https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers>valid W3C GlobalEventHandlers</a>

by name once <em>"connected"</em> to the HTML document.

<code>&lt;foo-bar onclick=hello&gt;</code> will <em>"automagically"^&trade;</em> register

the <code>hello (event) { }</code> handler defined on the custom element <code>class</code> definition.

<dt id=lifecycle:idle >6. Post-Render Idle

<dd>

Idling occurs after the <strong>Rendering</strong> routine consisting of

<strong>Token Binding</strong>, <strong>Template Iteration</strong>,

&amp; <strong>Event Registration</strong> has completed. This

<a

target=wikipedia

rel=external

href=https://en.wikipedia.org/wiki/Frame_rate#Modern_video_standards>

16<abbr title=Millisecond>ms</abbr>

</a>, or

<a

target=quora

rel=external

href=https://www.quora.com/What-is-60-frames-per-second>

60 Frames Per Second

</a> rate period coincides with the

<a

target=mdn

rel=external

href=https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback>

idle time between animation frames

</a>.

<dt id=lifecycle:events >7. Triggering Events <em>(On completion repeats rendering step #5 a, b, &amp; c)</em>

<dd>

There are a few ways events are registered by <strong>snuggsiツ</strong>.

Whether you choose a declarative registration <code>&lt;button onclick=onfoo&gt;</code>,

an imperative registration <code>onclick (event) {}</code>,

or an explicit registration <code>this.on ('click', this.onfoo)</code>,

the <strong>Rendering</strong> pipeline will force a

<a target=external rel=help href=https://www.phpied.com/rendering-repaint-reflowrelayout-restyle/>

<em>"reflow"</em> and <em>"repaint"</em>

</a> unless the <code>event</code> is explicitly prevented.

<p class=center><br>

<em>To prevent <strong>Rendering</strong> simply prevent the default event action by calling <br>

<code>event.prevent ()</code> within the custom element handler.</em>

<section view id=conventions>

<h1>Conventions</h1>

<article><!-- <medium-article> -->

<h2>Child Selection</h2>

<p> Here is where conventions on selecting children will live.

<header>Selecting a <strong>Single</strong> Child</header>

<code>Element.select (<em>selector</em>)</code>

<p>This is text about Element.select

<header>Selecting <strong>Multiple</strong> Childen</header>

<code>Element.selectAll (<em>selector</em>)</code>

<p>This is text about Element.selectAll

<aside>

<header>Relatd Links</header>

<ul>

<li>

<a rel=help target=external href=#>

Element.querySelector ()

</a>

<li>

<a rel=help target=external href=#>

Element.querySelectorAll ()

</a>

</aside>

</footer>Medium Article Link</footer>

</article>

<article><!-- <medium-article> -->

<header>The <abbr title='Push, Render, Precache, Lazy-load'>P.R.P.L.</abbr> Pattern</header>

<p>PRPL is a pattern for structuring and serving Progressive Web Apps (PWAs), with an emphasis on the performance of app delivery and launch. It stands for:

<ul>

<li><strong>P</strong>ush critical resources for the initial URL route.

Render initial route.

Pre-cache remaining routes.

Lazy-load and create remaining routes on demand.

<p>Beyond targeting the fundamental goals and standards of <abbr title='Progressive Web Apps'>P.W.A.</abbr>s, <abbr title='Push, Render, Precache, Lazy-load'>P.R.P.L.</abbr> strives to optimize for:

<ul>

<li> Minimum time-to-interactive

<ul>

<li>Especially on first use (regardless of entry point)

<li>Especially on real-world mobile devices

</ul>

<li>Maximum caching efficiency, especially over time as updates are released

<li>Simplicity of development and deployment

<p><abbr title='Push, Render, Precache, Lazy-load'>P.R.P.L.</abbr> is inspired by a suite of modern web platform features, but it’s possible to apply the pattern without hitting every letter in the acronym or using every feature.

<aside>

<header>Relatd Links</header>

<ul>

<li>

<a rel=help target=external href=https://www.youtube.com/watch?v=4bZvq3nodf4>

Progressive Performance <em>(Chrome Dev Summit)</em>

</a>

<li>

<a rel=help target=external href=https://developers.google.com/web/fundamentals/performance/prpl-pattern/>

<abbr title='Push, Render, Precache, Lazy-load'>P.R.P.L.</abbr> Pattern

</a>

<li>

<a rel=help target=external href=https://www.slideshare.net/grgur/prpl-pattern-with-webpack-and-react>

<abbr title='Push, Render, Precache, Lazy-load'>P.R.P.L.</abbr> Pattern with Webpack and React

</a>

<li>

<a rel=help target=external href=https://news.ycombinator.com/item?id=13751466>

Responses to <abbr title='Push, Render, Precache, Lazy-load'>P.R.P.L.</abbr> Pattern

</a>

</aside>

</footer>Medium Article Link</footer>

</article>

<header>Bundling &amp; Transpilation</header>

<section view id=antipatterns>

<h1>Anti-Patterns</h1>

<article>

<header>Talking to Strangers</header>

<p>

Should never reach outside of your component to talk to siblings.

There should be a "parent container" component that "sandboxes" in related components.

<footer></footer>

</article>

<article>

<header>Doing more than 16<abbr title=Milliseconds>ms</abbr> of Work</header>

<footer></footer>

</article>

<article>

<header>Unnecessary Reflow</header>

<footer></footer>

</article>

<article>

<header>Unnecessary Repaint</header>

<footer></footer>

</article>

<section view id=interfaces>

<h1>Interfaces</h1>

<p>This is some content about interfaces

<section id=interfaces:element>

<header><code>Element</code></header>

<p>Documentation about interfaces:element

<section id=interfaces:element:select>

<header><code>Element.select</code></header>

<p>Documentation about interfaces:element:select

<footer>This is the footer</footer>

</section>

<section id=interfaces:element:selectAll>

<header><code>Element.selectAll</code></header>

<p>Documentation about interfaces:element:select

<footer>This is the footer</footer>

</section>

</section>

<section view id=events>

<h1>Events</h1>

<section view id=tokens>

<h1>Tokens</h1>

<section view id=slots>

<h1>Slots</h1>

<section view id=context>

<h1>Context</h1>

<section view id=mixins>

<h1>Mixins</h1>

<h3>Further Learning</h3>

<ul>

<li>

<a href=/mixins>&lt;mixins&gt;</a>

<li>

<a

rel=help

target=wikipedia

href=https://en.wikipedia.org/wiki/Mixin>Mixin: Object Oriented Programing Concepts</a>

<li>

<a

rel=help

target=mdn

href=https://developer.mozilla.org/en-US/docs/Glossary/Mixin>Mix-in Definition</a>

<li>

<a

rel=help

target=mdn

href=https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#Mix-ins>Class Mix-ins</a>

</ul>

<header>Examples</header>

<details>

<summary><a href=/examples#html>&lt;custom-elements&gt;</a></summary>

<nav>

<ul>

<li>

<a href=/examples/hello-world>&lt;hello-world&gt;</a>

<li>

<a href=/examples/header-group/example.html>&lt;header-group&gt;</a>

<li>

<a href=/examples/github-ribbon/example.html>&lt;github-ribbon&gt;</a>

<li>

<a href=/examples/add-subtract>&lt;add-subtract&gt;</a>

<li>

<a href=/examples/input-output.html>&lt;input-output&gt;</a>

<li>

<a href=/examples/to-do>&lt;to-do&gt;</a>

<li>

<a href=/examples/multiple-choice>&lt;multiple-choice&gt;</a>

<li>

<a href=/examples/infinity-calendar>&lt;infinity-calendar&gt;</a>

<li>

<a href=/examples/nav-view/example.html>&lt;nav-view&gt;</a>

<li>

<a href=/examples/user-list>&lt;user-list&gt;</a>

<li>

<a href=/examples/fidget-spinner>&lt;fidget-spinner&gt;</a>

</ul>

</nav>

</details>

<details>

<summary><a href=/examples#components>&lt;web-components&gt;</a></summary>

<nav>

<ul>

<li>

</ul>

</nav>

</details>

<details>

<summary><a title='<template>' href=/examples#template>&lt;template&gt;</a></summary>

<nav>

<ul>

<li>

<a title=Collections href=examples#template:collections>Collections</a>

<li>

<a title=Collections href=examples#template:object>Object</a>

</nav>

</details>

<details>

<summary><a href=/examples#polyfills>&lt;polyfills-&gt;</a></summary>

<nav>

<ul>

<li>

<a href=/examples/datalist->&lt;datalist-&gt;</a>

</nav>

</details>

<details>

<summary><a title=Mixins href=/examples#mixins>Mixins ()</a></summary>

<nav>

<ul>

<li>

<a

title=Validate

href=#mixins:validate >

Validate

</a>

<li>

<!-- https://w3c.github.io/web-animations/#use-cases -->

<!-- https://discourse.wicg.io/t/proposal-wait-for-element-to-transition/2225 -->

<!-- https://medium.com/@adaptivepath/jedi-principles-of-ui-animation-2b88423b1dac -->

<!-- https://hackernoon.com/how-to-create-fancy-revealing-animations-with-these-simple-css-tricks-5b34614ae69a -->

<a title=Animate href=#>Animate</a>

<li>

<a title=Worker href=#>Worker</a>

<li>

<!-- https://www.smashingmagazine.com/2017/09/guide-virtual-reality-web-developers/?utm_source=frontendfocus&utm_medium=email -->

<a href=#>

<abbr title='Virtual Reality'>VR</abbr> <em>(Virtual Reality)</em>

</a>

<li>

<abbr title='Reactive JS'>RxJS</abbr> <em>(ReactiveJS)</em>

</nav>

</details>

<footer role=contentinfo>

<header><a title=snuggsiツ href=/>snuggsiツ</a></header>

<em>Copyright &copy; 2017-2024 A <strong><a rel=external target=devpunks title=devPunks href=//github.com/devpunks>devPunks</a></strong> project</em>