Alchemist (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:

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])]]
      : ''
])
/*
<section class="section">
  <h1>Calendar of the Witchmothers</h1>
  <hr>
  <ul>
    <li>It is day 11 of Winter; 77 til Spring.</li>
    <li>It is day 7 of the New Moon; Waxing happens in 33% of a day, or 1/6/2025, 3:56:25 PM.</li>
    <li>It is day 7 of the Jester's Moon; 22 til the Wizard's.</li>
    <li>The current time is 0:21:25, or 8:01:43 AM.</li>
  </ul>
</section>
*/

(src: witch-clock)

Using it alongside WebComponents is simple:

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!

// SAFE: NOT THIS TIME, HACKER!!
this.replaceChildren(alchemize(['div', userInput]))
// <div>&lt;h1&gt;hello world&lt;/h1&gt;</div>

// UNSAFE: CODE INJECTIONS AHOY!
this.replaceChildren(profane('div', userInput))
// <div><h1>hello world</h1></div>

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:

npm i -S html-alchemist

Or use pnmp or whatever.

Then you can import it in your project:

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:

alchemize(['hr'])
// <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.

alchemize(['h1', 'hello world'])
// <h1>hello world</h1>

To add properties to the tag, follow the tag name with an object. Its keys and values will be translated into properties.

alchemize(['button', { onclick: () => { ... } }, 'Click me!'])
// <button onclick="...">Click me!</button>

Tag names follow a special syntax that allows you to define classes and IDs without entering them as properties, the same way Reagent does.

alchemize(['input.my-input-style#signup-form-username', { type: 'text' }])
// <input id="signup-form-username" class="my-input-style" type="text" />

You can also notate direct descendents, such as for nested style semantics.

alchemize(['main.container>section>article#content', 'Hello world!'])
// <main class="container"><section><article id="content"></article></section></main>

Because Alchemist produces normal HTML entities, you can query them and add event listeners using browser-standard APIs.

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:

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 alchemize is called.

alchemize(['div.welcome', () => 'bonjour!'])
// <div class="welcome">bonjour!</div>

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.

alchemize('hello!')
// #text hello!
alchemize(() => 'bonjour!')
// #text bonjour!

Inputs of length 0 return an empty span.

alchemize([])
// <span></span>

Unlike Reagent, inputs do not strictly need to begin with an HTML tag name. Without an explicit tag name, div is used.

alchemize([['h1', 'have you heard the good word'], ['p', 'the word is "bird"']])
// <div><h1>have you heard the good word</h1><p>the word is "bird"</p></div>

When inner expressions are lists that don't begin with a tag name, the outer expression's tag name is used.

alchemize(['div.content', [['h1', 'have you heard the good word'], ['p', 'the word is "bird"']]])
// <div class="content"><h1>have you heard the good word</h1><p>the word is "bird"</p></div>

That's it. Now you know alchemy.

Allowing Unsafe Inputs

To allow code injection, Alchemist exports profane, 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.

const userBlogPost = 'Dear diary, today I became a <script> tag.'
profane('p', userBlogPost)
// <p>Dear diary, today I became a <script> tag.</p>

Convenience

Sometimes I like typing fewer characters. Alchemist also exports these functions:

• snag(elemId)
  • equivalent to
    document.getElementById(elemId)
• listento(elemId, eventName, callback)
  • equivalent to
    snag(elemId).addEventListener(eventName, callback)
• refresh(elemId, expr)
  • equivalent to
    snag(elemId).replaceChildren(alchemize(expr))
  • ...but you can also pass an HTML element as elemId directly!

Development

Run the test suite:

npm test

Get test coverage info:

npm run cov

To modify the main site:

# run the playground server
npm run dev
# edit a recipe
emacs www/playground.js
# now visit http://localhost:3000/
# it will update whenever alchemist or any recipes change

License

Caveat emptor. I mean, ISC.