mich-h

Create HAST-compliant virtual dom trees of HTML using hyperscript compatible syntax or JSX, just in ~570 bytes.

You might also be interested in hyperscript - a builder for real dom elements.

JSX CodePen Example

Highlights

• Tiny: Very lightweight, ~600 bytes gzip + minify and the UMD wrapper.
• Defaults: Sane defaults and tiny css selector parser.
• Components: Can be used to create Stateless or Statefull Components.
• Specificaition: Creates HAST-compliant AST trees.
• Customization: Supports JSX, custom tags and attributes.
• Minimalist: Really, just a builder of AST trees.
• Compatibility: Same as hyperscript, but creates virtual DOM.
• Friendly: Plays well with browserify users.
• Bundled: Available as ES6 Module, CommonJS, UMD.
• SSR: Supports server-side rendering through mich-to-html.
• Clean: Does not mess with DOM or anything.

Table of Contents

• Install
• Usage
• API
  • michH
• Notes
  • The className and class
  • The data-* and dataset
  • The styles
• Related
• Contributing
• Building docs
• Running tests
• Author
• License

(TOC generated by verb using markdown-toc)

Install

Install with npm

$ npm install mich-h --save

or install using yarn

$ yarn add mich-h

Builds are also available on unpkg CDN, so iniclude

<script src="https://unpkg.com/mich-h/dist/mich-h.min.js"></script>

then access mich-h through the michH global property - notice the uppercased H letter.

<script>
  const h = michH
  const node = h('h1.hero#home.big', 'Hello World')

  console.log(node)
</script>

Try CodePen or JSBin Example

Usage

For more use-cases see the tests

const h = require('mich-h')

const ast = h('div#page.foo.bar.qux', { className: 'ok fool' },
  h('#header',
    h('h1.classy', 'hello', { style: 'background-color: #333; color: purple' })),
  h('nav#menu', { style: {'background': '#2f2', 'font-size': '12px' } },
    h('ul', [
      // notice `dataset` and `data-zaz`
      // both will be set to `properties.dataset`
      h('li', 'one', { dataset: { foo: 'bar', qux: 'ok' }, 'data-zaz': 'huh' }),
      h('li.sec', 'two', { className: ['huh'] }),
      h('li', { 'data-foo': 'hi' }, 'three')
    ])),
  h('h2#title', 'content title',  { style: {'background-color': 'red'} }),
  // notice `.first` and `className: 'foobie'`
  // both will be set in `properties.className` array 
  h('p.first',
    'so it is just like a templating engine,\n',
    { className: 'foobie' },
    'but easy to use inline with javascript',
    { onclick: () => {} }),
  h('p',
    { className: 'lastParagraph' },
    'the intention is for this to be used to create\n',
    h('strong', 'charlike', {
      className: ['bold'],
      style: 'background: white; color: green'
    }),
    ' reusable, interactive html widgets.'))

console.log(ast)

Or with modern JSX syntax, adding JSX Pragma somewhere at the top and using some transpiler - Rollup, Webpack or Babel with babel-plugin-transform-react-jsx.

/** @jsx h */
const h = require('mich-h')

const onclick = (e) => console.log('hooray it is clicked!')
const list = <ul>
  <li dataset={{ foo: 'bar', qux: 'ok' }} data-zaz="huh">one</li>
  <li className="sec huh">two</li>
  <li data-foo="hi">three</li>
</ul>

const ast = <div id="page" className="foo bar qux ok fool">
  <div id="header">
    <h1 className="classy" style="background-color: #333; color: purple">hello</h1>
  </div>
  <nav id="menu" style="background: #2f2;font-size: 12px;">
    {list}
  </nav>
  <h2 id="title" style="background-color: red;">content title</h2>
  <p className="first foobie" onclick={onclick}>so it is just like a templating engine,
    but easy to use inline with javascript
  </p>
  <p className="lastParagraph">the intention is for this to be used to create
    <strong className="bold" style="background: white; color: green">charlike </strong>
    reusable, interactive html widgets.
  </p>
</div>

console.log(ast)

Examples:

• CodePen Example, using JSX
• Showing AST of pseudo JSX router

API

michH

Virtual DOM builder that is compatible to hyperscript, so it takes any number of arguments that can be string, object, or array. But the first one selector always should be a simple css-like selector supported by mich-parse-selector. For example .foo.bar creates a node with tag name div and classes foo bar. Or selector like p.foo#hero.bar creates a node with id hero, classes foo and bar, and tag name p.

Params

• selector {String}: simple selector; supports IDs, classes and tag name only
• props {Object}: an attributes for the tag; can be in any position (i.e 4th)
• children {String|Array}: a child nodes; can be in any position (i.e. 2nd or 5th)
• returns {Object}: a HAST compliant node

Example

const h = require('mich-h')

const node = h('a.foo#brand.bar.btn-large.xyz', {
  className: 'btn'
  href: 'https://i.am.charlike.online'
}, 'Charlike Web')

console.log(node.type) // => 'element'
console.log(node.tagName) // => 'p'
console.log(node.properties.id) // => 'brand'

console.log(node.properties.href)
// => 'https://i.am.charlike.online'

console.log(node.properties.className)
// => [ 'foo', 'bar', 'btn-large', 'xyz', 'btn' ]

console.log(node.children.length) // => 1
console.log(node.children[0])
// => { type: 'text', value: 'Charlike Web' }

Notes

The className and class

Notice that we write className, but class is also supported. Just in old javascript versions it may throw you an error if you try to write it as object key. You will just always get an array as end result in the generated node - they are just concatenated.

const tag = h('.foo', {
  className: 'bar'
})

console.log(tag.properties.className)
// => [ 'foo', 'bar' ]

// or passing multiple classes in className
const div = h('.bar', {
  className: ['qux', 'xyz']
})
console.log(div.properties.className)
// => [ 'bar', 'qux', 'xyz]

The data-* and dataset

Another that you should be aware of is that we write dataset instead of data when want to define a data-* attributes for a tag while using props object. That name comes from DOM - it saves each data attribute to an object dataset in each DOM element. You can still define each data-* attribute as key in props object, like this

const div = h('.foo', {
  'data-abc': 'hello',
  'data-bar': 'world'
})

// another way is using `dataset`
const node = h('.foo', {
  dataset: {
    abc: 'hello',
    bar: 'world'
  }
})

While using JSX you still can define it in both styles

const node = <div data-abc="hello" dataset={{ bar: 'world' }}>Hi</div>

The styles

Note that you can define style in both ways 1) using a string as value or 2) object as value.

const node = h('p', {
  style: 'background: red; font-size: 15px;'
})

console.log(node.properties.style)
// => 'background: red; font-size: 15px;'

Using above approach you'll end up finally with a node that has a properties.style a string, because we don't parse the value. So what you pass, you'll get.

If you pass an object, you'll have an object. Here in that example we'll use JSX, but it is the same as using the h-calls.

const pTagStyle = {
  background: 'red',
  'font-size': '15px'
}
const node = <p style={pTagStyle}>Hello World</p>

console.log(node.properties.style.background) // => 'red'
console.log(node.properties.style)
// => { background: 'red', 'font-size': '15px' }

Notice that we also don't decamelize style keys, so you should use quotes.

Related

• hastscript: Hyperscript compatible DSL for creating virtual HAST trees | homepage
• hyperscript: Create HyperText with JavaScript, on client or server. | homepage
• mich-parse-selector: Tiny parser for simple CSS selectors, just in ~300 bytes. Pretty similar to what is done in hyperscript | homepage
• posthtml: HTML/XML processor | homepage
• rehype: HTML processor powered by plugins | homepage
• reshape: A plugin-based html template engine | homepage
• virtual-dom: A batched diff-based DOM rendering strategy | homepage
• virtual-html: Convert given HTML into Virtual DOM object | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Please read the contributing guidelines for advice on opening issues, pull requests, and coding standards.
If you need some help and can spent some cash, feel free to contact me at CodeMentor.io too.

In short: If you want to contribute to that project, please follow these things

1. Please DO NOT edit README.md, CHANGELOG.md and .verb.md files. See "Building docs" section.
2. Ensure anything is okey by installing the dependencies and run the tests. See "Running tests" section.
3. Always use npm run commit to commit changes instead of git commit, because it is interactive and user-friendly. It uses commitizen behind the scenes, which follows Conventional Changelog idealogy.
4. Do NOT bump the version in package.json. For that we use npm run release, which is standard-version and follows Conventional Changelog idealogy.

Thanks a lot! :)

Building docs

Documentation and that readme is generated using verb-generate-readme, which is a verb generator, so you need to install both of them and then run verb command like that

$ npm install verbose/verb#dev verb-generate-readme --global && verb

Please don't edit the README directly. Any changes to the readme must be made in .verb.md.

Running tests

Clone repository and run the following in that cloned directory

$ npm install && npm test

Author

Charlike Mike Reagent

• github/tunnckoCore
• twitter/tunnckoCore
• codementor/tunnckoCore

License

Copyright © 2016-2017, Charlike Mike Reagent. Released under the MIT License.

This file was generated by verb-generate-readme, v0.4.3, on March 03, 2017.
Project scaffolded using charlike cli.