@storybook-tiny/webcomponent 1.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2024-present, commenthol and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @storybook-tiny/webcomponent
+
+A tiny storybook for [webcomponents][].
+
+# usage
+
+initial setup:
+
+```sh
+# add to your project
+npm i -D @storybook-tiny/webcomponent
+
+# install storybook template with npm
+npx storybook-tiny
+# or with pnpm
+npx storybook-tiny -p pnpm
+```
+
+define some stories:
+
+```js
+import '@storybook-tiny/webcomponent'
+
+// define some custom elements
+window.customElements.define('x-text', class extends HTMLElement {
+  connectedCallback() {
+    const shadow = this.attachShadow({ mode: 'closed' })
+    shadow.innerHTML = `<h1>It works!</h1>`
+  }
+})
+
+// describe your stories...
+const storyText = {
+  title: 'Text',
+  component: '<p>Some Text</p>' // component is mounted with .innerHTML
+}
+
+const storyXtext = {
+  title: 'x-text',
+  component: () => document.createElement('x-text')
+}
+
+// define stories in storybook
+const storybook = document.createElement('storybook-tiny')
+storybook.stories = [
+  '<small>Components</small>',
+  storyText,
+  storyXtext
+]
+document.getElementById('app').appendChild(storybook)
+```
+
+Then run with vite:
+
+```sh
+npx vite
+```
+
+# license
+
+MIT licensed
+
+[webcomponents]: https://developer.mozilla.org/en-US/docs/Web/API/Web_components

package/bin/storybook-tiny.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+import { install } from '@storybook-tiny/setup'
+import { fileURLToPath } from 'url'
+
+const config = {
+  rootDir: fileURLToPath(new URL('..', import.meta.url)),
+  devDependencies: ['@storybook-tiny/webcomponent', 'vite'],
+  files: ['stories/*', 'vite.config.js'],
+  post: [
+    {
+      sed: [
+        '-i',
+        "import '../src/Storybook'",
+        "import '@storybook-tiny/webcomponent'",
+        'stories/stories.js'
+      ]
+    }
+  ]
+}
+
+install(config)

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@storybook-tiny/webcomponent",
+  "version": "1.0.0",
+  "description": "A tiny storybook for webcompoments",
+  "keywords": [
+    "storybook",
+    "storybook-tiny",
+    "webcomponent"
+  ],
+  "homepage": "https://github.com/commenthol/storybook-tiny/tree/main/packages/webcomponent#readme",
+  "bugs": {
+    "url": "https://github.com/commenthol/storybook-tiny/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/commenthol/storybook-tiny.git",
+    "directory": "packages/webcomponent"
+  },
+  "license": "MIT",
+  "author": "commenthol <commenthol@gmail.com>",
+  "maintainers": [
+    "commenthol <commenthol@gmail.com>"
+  ],
+  "type": "module",
+  "main": "./src/Storybook.js",
+  "bin": {
+    "storybook-tiny": "./bin/storybook-tiny.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "stories",
+    "vite.config.js"
+  ],
+  "dependencies": {
+    "@storybook-tiny/setup": "1.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.9.0",
+    "eslint": "^9.9.0",
+    "globals": "^15.9.0",
+    "vite": "^5.4.1"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "lint": "eslint"
+  }
+}

package/src/Storybook.js

@@ -0,0 +1,156 @@
+import styles from './Storybook.module.css'
+import { WcElement, define, cssUnit } from './WcElement'
+
+const getLocationHash = () => decodeURIComponent(location.hash.substring(1))
+
+const template = `
+<main class="${styles.storybook}">
+  <aside>
+    <h4><a></a></h4>
+    <div></div>
+  </aside>
+  <section class="stories">
+  </section>
+</main>
+`
+
+const defaultStory = `
+<p class="${styles.storybookSectionP}">
+  The tiny storybook for<span> </span>
+  <a
+    href="https://developer.mozilla.org/en-US/docs/Web/API/Web_components"
+    target="_blanc"
+    rel="norel noreferrer"
+  >
+    webcomponents
+  </a>
+</p>
+`
+
+class Storybook extends WcElement {
+  $ = {}
+  state = {}
+
+  static attributes = {
+    header: 'Storybook Tiny',
+    href: '/stories/index.html',
+    width: 130,
+    stories: []
+  }
+
+  connectedCallback() {
+    this.innerHTML = template
+    const { $ } = this
+    $.aside = this.querySelector('main > aside')
+    $.h4 = $.aside.querySelector('h4 a')
+    $.titles = $.aside.querySelector('div')
+    $.story = this.querySelector('section')
+    this.addEventListener(window, 'hashchange', () => this._renderStory())
+    this.render()
+  }
+
+  render() {
+    const { $ } = this
+    $.h4.textContent = this.header
+    $.h4.href = this.href
+    $.aside.style.flexBasis = cssUnit(this.width)
+    $.titles.innerHTML = ''
+    for (const story of this.stories) {
+      const $el = document.createElement('storybook-tiny-story')
+      $el.story = story
+      $.titles.appendChild($el)
+    }
+    this._renderStory()
+  }
+
+  _renderStory() {
+    const locHash = getLocationHash()
+    if (this.state.title === locHash) {
+      return
+    }
+
+    let renderStory = defaultStory
+
+    for (const story of this.stories) {
+      if (typeof story === 'object') {
+        const { title, component } = story
+        if (title && title === locHash && component) {
+          renderStory = component
+          this.state.title = title
+        }
+      }
+    }
+
+    const { $ } = this
+    $.story.innerHTML = ''
+    try {
+      switch (typeof renderStory) {
+        case 'string':
+          $.story.innerHTML = renderStory
+          break
+        case 'function':
+          $.story.appendChild(renderStory())
+          break
+        default:
+          throw new Error(
+            `Can't render "${this.state.title}"; Component must be string or function`
+          )
+      }
+    } catch (err) {
+      console.error(err)
+      const error = document.createElement('storybook-tiny-error')
+      error.message = err.message
+      error.stack = err.stack
+      $.story.appendChild(error)
+    }
+  }
+}
+
+define('storybook-tiny', Storybook)
+
+class Story extends WcElement {
+  connectedCallback() {
+    if (typeof this.story === 'string') {
+      this.innerHTML = this.story
+      return
+    }
+
+    this.addEventListener(window, 'hashchange', () => this.render())
+    const { title } = this.story
+    this.innerHTML = `
+      <div>
+        <a 
+          href="#${title}" 
+          tabindex="0"
+          role="button"
+        >${title}</a>
+      </div>
+    `
+    this.render()
+  }
+
+  render() {
+    const { title } = this.story
+    const locHash = getLocationHash()
+    this.querySelector('a').className = locHash === title ? styles.active : ''
+  }
+}
+
+define('storybook-tiny-story', Story)
+
+class StoryError extends WcElement {
+  static attributes = { message: '', stack: '' }
+
+  render() {
+    this.innerHTML = `
+      <div class="${styles.error}">
+        <h2>Error</h2>
+        <p>${this.message}</p>
+        <p> </p>
+        <pre style="white-space: pre-wrap">${this.stack}</pre>
+      </div>
+    `
+  }
+}
+
+define('storybook-tiny-error', StoryError)

package/src/Storybook.module.css

@@ -0,0 +1,63 @@
+.storybook {
+  font-family: Arial, Helvetica, sans-serif;
+  display: flex;
+}
+
+.storybook>aside {
+  border-right: 1px solid rgba(0, 0, 0, 0.1);
+  overflow-y: auto;
+  max-height: calc(100vh - 3em);
+  flex-grow: 0;
+  flex-shrink: 0;
+  flex-basis: 130px;
+}
+
+.storybook>aside>* {
+  padding-left: 5px;
+  padding-right: 5px;
+}
+
+.storybook aside a,
+.storybook aside a:visited {
+  color: blue;
+}
+
+.storybook aside a.active {
+  font-weight: bold;
+}
+
+.storybook>aside>small {
+  padding-top: 0.5em;
+  padding-bottom: 0.25em;
+  display: block;
+}
+
+.storybook>aside>h4 {
+  padding-top: 5px;
+  margin-top: 0;
+}
+
+.storybook>aside>h4 a,
+.storybook>aside>h4 a:visited {
+  text-decoration: none;
+  color: unset;
+}
+
+.storybook section {
+  flex: 1;
+}
+
+.storybookSectionP {
+  margin: 5px;
+}
+
+.error h2 {
+  color: rgb(255, 0, 115);
+  padding-top: 1em;
+  margin-top: 0;
+}
+
+.error {
+  padding: 0 1em 1em;
+  background-color: rgb(255, 0, 115, 0.1);
+}

package/src/WcElement.js

@@ -0,0 +1,145 @@
+/**
+ * class extening HTMLElement to enable deferred rendering on attribute changes
+ * either via `setAttribute(name, value)` or `this[name] = value`.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
+ * @example
+ * class Example extends WcElement {
+ *  // internal references go here
+ *  $ = {}
+ *  // define all observed attributes.
+ *  // attributes are accessible via `this[prop]`
+ *  // avoid using attributes which are HTMLElement properties
+ *  static attributes = {
+ *    text: 'Hi'
+ *  }
+ *  // as with HTMLElement 
+ *  connectedCallback() {
+ *    // do initial mount of component here
+ *    this._shadow = this.shadow = this.attachShadow({ mode: 'closed' })
+ *    this._shadow.innerHTML = `<div></div>`
+ *    this.$.div = this._shadow.querySelector('div')
+ *    this.render()
+ *  }
+ *  // render method called every time an attribute changes
+ *  render() {
+ *    this.$.div.textContent = this.text
+ *  }
+ * }
+ * // create a custom element with the `define` function (see below)
+ * define('x-example', Example)
+ * // create a DOM node and re-render via attribute or property changes
+ * const elem = document.createElement('x-example')
+ * elem.setAttribute('text', 'set attribute')
+ * elem.text = 'set property'
+ */
+export class WcElement extends HTMLElement {
+  _attr = {}
+  _removers = []
+
+  constructor() {
+    super()
+    this._attr = structuredClone(this.constructor.attributes || {})
+    observedAttributes(this)
+  }
+
+  /**
+   * set attribute and re-render
+   * @param {string} name
+   * @param {any} value
+   */
+  setAttribute(name, value) {
+    this._attr[name] = value
+    this.isConnected && this.deferredRender()
+  }
+
+  /**
+   * component must implement render()!
+   */
+  connectedCallback() {
+    this.render()
+  }
+
+  /**
+   * @param {string} name change attribute
+   * @param {any} _oldValue
+   * @param {any} newValue new value
+   */
+  attributeChangedCallback(name, _oldValue, newValue) {
+    this._attr[name] = newValue
+    this.deferredRender()
+  }
+
+  /**
+   * helper function to remove event listeners when component gets disconnected
+   * @param {HTMLElement} node
+   * @param {string} event
+   * @param {function} fn
+   */
+  addEventListener(node, event, fn) {
+    node.addEventListener(event, fn)
+    this._removers.push(() => node.removeEventListener(event, fn))
+  }
+
+  /**
+   * remove possible event listeners
+   */
+  disconnectedCallback() {
+    this._removers.forEach((remover) => remover())
+  }
+
+  /**
+   * deferred render
+   */
+  deferredRender() {
+    window.requestAnimationFrame(() => {
+      this.render()
+    })
+  }
+}
+
+/**
+ * re-render component when property changes
+ * @param {HTMLElement} elem 
+ */
+const observedAttributes = (elem) => {
+  for (const prop of Object.keys(elem._attr)) {
+    Object.defineProperty(elem, prop, {
+      get() {
+        return elem._attr[prop]
+      },
+      set(newValue) {
+        const oldValue = elem._attr[prop]
+        if (oldValue === newValue) return
+        elem._attr[prop] = newValue
+        elem.isConnected && elem.deferredRender()
+      }
+    })
+  }
+}
+
+/**
+ * defines a custom element adding observedAttributes from default static
+ * attributes
+ * @param {string} name custom element tag
+ * @param {HTMLElement} Element
+ */
+export const define = (name, Element) => {
+  Element.observedAttributes =
+    Element.observedAttributes || Object.keys(Element.attributes || [])
+  window.customElements.define(name, Element)
+}
+
+const toNumber = (n) => {
+  const _n = Number(n)
+  return !isNaN(_n) ? _n : undefined
+}
+
+/**
+ * convert number to css unit
+ * @param {numbers|string} unit 
+ * @returns {string}
+ */
+export const cssUnit = (unit) => {
+  const n = toNumber(unit)
+  return typeof n === 'number' ? `${n}px` : unit
+}

package/stories/index.html

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>@storybook-tiny/webcomponent</title>
+    <style>
+      body {
+        margin: 0;
+        padding: 0;
+      }
+    </style>
+  </head>
+
+  <body>
+    <!-- open with http://localhost:5173/stories/index.html -->
+    <div id="app"></div>
+    <script type="module" src="/stories/stories.js"></script>
+  </body>
+</html>

package/stories/some.stories.js

@@ -0,0 +1,93 @@
+// define some custom elements
+window.customElements.define(
+  'x-button',
+  class extends HTMLElement {
+    connectedCallback() {
+      this.shadow = this.attachShadow({ mode: 'open' })
+      this.$ = document.createElement('button')
+      this.$.addEventListener('click', () => alert('Hi'))
+      this.shadow.appendChild(this.$)
+      this.$.textContent = this.childNodes?.[0]?.textContent || 'Click Me'
+    }
+  }
+)
+
+window.customElements.define(
+  'x-counter',
+  class extends HTMLElement {
+    $ = {}
+    init = 0
+
+    static observedAttributes = ['init']
+
+    attributeChangedCallback(name, _oldValue, newValue) {
+      switch (name) {
+        case 'init':
+          this[name] = isNaN(Number(newValue)) ? 0 : Number(newValue)
+          break
+      }
+    }
+
+    connectedCallback() {
+      this.shadow = this.attachShadow({ mode: 'closed' })
+      this.shadow.innerHTML = `
+      <style>
+        :host {
+          font-size: 1.5em;
+        }
+        span {
+          padding-right: 0.25em;
+        }
+        span.count { 
+          display: inline-block; 
+          width: 4em;
+          text-align: right; 
+        }
+        button { 
+          font-size: 1em;
+        }
+      </style>
+      <div>
+        <span class="count"></span>
+        <span class="heart"></span>
+        <button>👍</button>
+        <button>👎</button>
+      </div>
+    `
+      this.$.count = this.shadow.querySelector('.count')
+      this.$.heart = this.shadow.querySelector('.heart')
+      this.$.buttons = this.shadow.querySelectorAll('button')
+      this.$.buttons[0].addEventListener('click', () => {
+        this.init += 1
+        this.render()
+      })
+      this.$.buttons[1].addEventListener('click', () => {
+        this.init -= 1
+        this.render()
+      })
+      this.render()
+    }
+
+    render() {
+      this.$.count.textContent = this.init
+      this.$.heart.textContent =
+        this.init === 0 ? '🤍' : this.init > 0 ? '❤️' : '💔'
+    }
+  }
+)
+
+// define your stories
+export const storyButton = {
+  title: 'x-button',
+  component: '<x-button>My Text</x-button>'
+}
+export const storyCounter = {
+  title: 'x-counter',
+  component: () => document.createElement('x-counter')
+}
+export const storyError = {
+  title: 'Error',
+  component: () => {
+    throw new Error('baam')
+  }
+}

package/stories/stories.js

@@ -0,0 +1,16 @@
+import '../src/Storybook'
+import {
+  storyButton,
+  storyCounter,
+  storyError
+} from './some.stories'
+
+const storybook = document.createElement('storybook-tiny')
+storybook.stories = [
+  '<small>Components</small>',
+  storyButton,
+  storyCounter,
+  storyError
+]
+
+document.getElementById('app').appendChild(storybook)

package/vite.config.js

@@ -0,0 +1,5 @@
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: []
+})