have you heard the good word
the word is "bird"
Reagent-style HTML templating, for use with WebComponents.
npm install html-alchemist
Based on Reagent, Alchemist supplies an alchemize function that converts list expressions into HTML entities. It is designed to work alongside WebComponents, replacing your need for React and JSX in one fell swoop. It is very small, under 2kb when minified. Its closest cousin is VanJS.
Example:
``js`
alchemize([
'section.section',
['h1', 'Calendar of the Witchmothers'],
['hr'],
['ul',
['li', explainSeason(witchy)],
['li', explainPhase(witchy)],
['li', explainMonth(witchy)],
['li', explainTime(witchy)]
],
holidays
? [['h2', 'Holidays'],
['hr', ''],
['ul', holidays.map(h => ['li', h])]]
: ''
])
/*
Calendar of the Witchmothers
*/
(src: witch-clock)
Using it alongside WebComponents is simple:
`js
import { alchemize, snag } from "./alchemist.js"
function counterview () {
// no reactive state. you control when and what to re-render.
let i = 0
function onclick () {
// interact directly with the DOM. dispel the magic.
snag('counter').innerText = String(++i)
}
// stop writing end tags. set attributes tersely.
return alchemize(['button#counter', { onclick, style: 'width: 100%;' }, i])
}
// forget react. make your own elements with webcomponents.
class CounterApp extends HTMLElement {
connectedCallback () {
this.appendChild(counterview())
}
}
customElements.define('counter-app', CounterApp)
`
Text input is HTML-escaped by default.
Alchemist supplies a function called profane
for alchemizing trusted inputs, like parsed Markdown.
Be sure to use it when you need it!
`js
// SAFE: NOT THIS TIME, HACKER!!
this.replaceChildren(alchemize(['div', userInput]))
// <h1>hello world</h1>
// UNSAFE: CODE INJECTIONS AHOY!
this.replaceChildren(profane('div', userInput))
//
There are several example apps you can check out on the website, including todo and diary apps. You may find the playground especially useful for experimentation.
Install
Get it on NPM:
bash
npm i -S html-alchemist
`Or use pnmp or whatever.
Then you can import it in your project:
js
import { alchemize } from 'html-alchemist'
`Usage
Alchemist uses a list-based approach to structuring HTML. It's already a list of lists, and who likes writing end tags?
Your most basic expression is a list with one element, which is used as the name of an HTML tag:
js
alchemize(['hr'])
//
`To add content to a node, you need a list of two things. The first is the node's HTML tag. The second is used as the node's content, and may be another alchemical expression.
js
alchemize(['h1', 'hello world'])
// hello world
`To add properties to the tag, follow the tag name with an object. Its keys and values will be translated into properties.
js
alchemize(['button', { onclick: () => { ... } }, 'Click me!'])
//
`Tag names follow a special syntax that allows you to define classes and IDs without entering them as properties, the same way Reagent does.
js
alchemize(['input.my-input-style#signup-form-username', { type: 'text' }])
//
`You can also notate direct descendents, such as for nested style semantics.
js
alchemize(['main.container>section>article#content', 'Hello world!'])
//
`Because Alchemist produces normal HTML entities, you can query them and add event listeners using browser-standard APIs.
js
const node = document.getElementById('signup-form-username')
node.addEventListener('input', (event) => {
// fires whenever the input's value changes
})
`Of course, you can also pass event handlers directly in alchemical expressions:
js
let i = 0
function onclick () {
document.getElementById('counter').innerText = String(++i)
}
return alchemize(['button#counter', { onclick }, i])
`You can also nest functions in alchemical expressions to execute when
is called.`js
alchemize(['div.welcome', () => 'bonjour!'])
// bonjour!
`This doesn't work on promises. Sorry. You'll have to deal with the hassle of event listeners instead.
Inputs that aren't lists can be either strings, which will be converted to HTML text nodes, or functions, which will be called and alchemized.
js
alchemize('hello!')
// #text hello!
alchemize(() => 'bonjour!')
// #text bonjour!
`Inputs of length 0 return an empty span.
js
alchemize([])
//
`Unlike Reagent, inputs do not strictly need to begin with an HTML tag name. Without an explicit tag name,
is used.`js
alchemize([['h1', 'have you heard the good word'], ['p', 'the word is "bird"']])
// have you heard the good word
the word is "bird"
`When inner expressions are lists that don't begin with a tag name, the outer expression's tag name is used.
js
alchemize(['div.content', [['h1', 'have you heard the good word'], ['p', 'the word is "bird"']]])
// have you heard the good word
the word is "bird"
`That's it. Now you know alchemy.
$3
To allow code injection, Alchemist exports
,
a function to ignore escaping HTML in untrusted strings.
Rather than providing an alchemical expression,
you provide an enclosing tag, with the text to escape.`js
const userBlogPost = 'Dear diary, today I became a