schneiderfelipe / hyperscript

📎 Create HyperText with Nim.

hyperscript

A functional Nim library for combining DOM pieces, with compile-time superpowers. hyperscript creates composable HTML and SVG with Nim, both client- and server-side:

import hyperscript

let example =
  h("div#page",
    h("div#header",
      h("h1.classy", "h", { style: {"background-color": "#22f"} })),
    h("div#menu", { style: {"background-color": "#2f2"} },
      h("ul",
        h("li", "one"),
        h("li", "two"),
        h("li", "three"))),
      h("h2", "content title",  { style: {"background-color": "#f22"} }),
      h("p",
        "so it's just like a templating engine,\n",
        "but easy to use inline with Nim\n"),
      h("p",
        "the intention is for this to be used to create\n",
        "reusable, interactive HTML widgets. "))

(Currently, only literal arguments are supported, but this limitation will be removed in a future release, see #8 and #10.)

Installation

hyperscript works with Nim 1.2.6+ and can be installed using Nimble:

$ nimble install hyperscript

How does it work?

The basic design consists of compiling down to efficient calls to the DOM (through the dom standard library). As such, the following,

let example = h("p#example",
  h("input.name[value=Name]",
    style: {"background": "yellow"},
  ),
)

compiles roughly to

let example =
  let node = document.createElement("p")
  for attr in items([("id", "example")]):
    node.setAttribute(attr[0], attr[1])
  for child in items([
    let node = document.createElement("input")
    for attr in items([("value", "Name"), ("class", "name"), ("style", "background: yellow;")]):
      node.setAttribute(attr[0], attr[1])
    node]):
    node.appendChild(child)
  node

(We intend to unroll all loops in the future, see #6.)

When not compiling to JavaScript, XmlNode objects are generated using the xmltree standard library. Using the C backend, for instance, the example above compiles to

let example =
  newXmlTree("p", [
      newXmlTree("input", @[],
        {"value": "Name", "class": "name", "style": "background: yellow;"}.toXmlAttributes,
      ),
    ], {"id": "example"}.toXmlAttributes,
  )

Some references

• hyperscript (original library, JavaScript)
• Hyperscript.jl (Julia)

Convert HTML snippets to hyperscript:

• Mithril HTML to hyperscript converter
• HTML2HyperScript

hyperscript's Issues

Scoped CSS

EDIT: CSS in Nim (JS).

Requirements:

• Scoped
• Server-side renderable
• No inline styles (most of the time?)
• Object style notation

Implement an element factory

The idea is to go beyond simple element generators but create simplified and efficient component/widget generators.

EDIT: Similar to how hyperscript-helpers do it.
hyperaxe and elementx are also inspirations.

This can be done without any overhead using macros.

Generate documentation

Test boolean attributes

Support event listener options

Stop propagation, prevent default, etc.

Support indicating multiple classes at construction

With 70bb94d we lost the ability of indicating multiple classes at tag construction. That heavily simplifies the code, which is the correct behavior for the class attribute.

But having a way of indicating multiple classes is beneficial. Maybe using a special classList named parameter?

render function that mounts (in JS) or prints (other backends)

render could accept an object and a mount point:

h("h1", "Hello world!").render(document.getElementById("root"))

Emmet notation for nested tags

Like this.

Test HTML entity escaping

Support non-literals (variables, calls, etc.)

Currently, only literals are supported (tags, ids, styles, classes, etc. should only work with them).

This is strongly related to #8.

things related to building nodes

We need a way of unifying building and modifying nodes that works for both literals and non-literal values.

Should use dom.cloneNode and avoid dom.createElement?

Some frameworks seem to do this (e.g., Solid).

Code gets repeated in the output

As described here.

Should unroll loops that add children and attributes?

Benchmarks required.

Components through the tag name slot?

Maybe functions instead of strings?

func widget(...): ... =
  ...

h(widget, {...}, ...)  # ?

How useful is that?

Use xom as backend

xom

Support mutating objects

Use a composable API (like D3.js, jQuery, etc.).

EDIT: roadmap

• #13
  • appending children
  • adding general attributes
  • inserting event listeners
  • stuff related to CSS selectors
    • adding classes
    • adding IDs
    • modifying tags?
• things related to destroying nodes
  • removing children
  • removing attributes
  • removing event listeners?
• unroll loops for not-so-large changes (up to eight items)
  • for children
  • for attributes
  • for events
• tests for everything above