Never Patronize Mothers

    uhtml
    TypeScript icon, indicating that this package has built-in type declarations

    3.1.0 • Public • Published

    µhtml

    Downloads build status Coverage Status CSP strict

    snow flake

    Social Media Photo by Andrii Ganzevych on Unsplash

    micro html is a ~2.5K lighterhtml subset to build declarative and reactive UI via template literals tags.

    📣 Community Announcement

    Please ask questions in the dedicated discussions repository, to help the community around this project grow


    V3.0 Update

    • removed IE and legacy Edge compatibility
    • simplified template parsing
    • cleaned up dependencies

    V2.8 Update

    • added µhandlers foreign export to enable arbitrary attributes handling!
    import {html, foreign} from 'uhtml';
    
    const handler = (node, name, value) => {
      // P, any, {data: 123}
      console.log(node, name, value);
      // return null/undefined to remove it
      return value.data;
    };
    
    html`<p any=${foreign(handler, {data: 123})}>foreign</p>`;

    V2.5 Update

    • an interpolated value, within a DOM element, can now be a function, enabling a world of µhtml extending possibilities, including intents, hence aligning the behavior with both lighterhtml and hyperHTML. That is: <el>${callback}</el>! The callback will be invoked with the comment pin/placeholder as unique argument, where its parentNode would be the element containing such comment, if needed, and its returned value will be passed along the same mechanism that resolves already all other cases.

    V2.4 Update

    • a new ?attribute=${value} prefix, with a question mark, has landed, after this long debate, and based to the fact µhtml never wants to be ambiguous. However, the mighty lit-html put an end to the debate, disambiguating through a ? question mark prefix, which explicits developers intents, and works well across browsers. So that's it: whenever you expect an attribute to be in, or out, use ?name=${value} and win the day 🥳

    V2.2 Update

    • the new.js file has been renamed as es.js to align with other modules of mine that follow the same pattern.
    • this module now exports its very same utilities via uhtml/async, in order to automatically resolve asynchronous values passed along the template. Please note this means that exported render, html, and svg tags, are all asynchronous, hence these all return a promise.
    • the async.js file is now published too, compatible with ES2015+ browsers (no async / await used)

    How To

    Example

    import {render, html, svg} from 'uhtml/async';
    
    render(document.body, html`a${Promise.resolve('b')}c`);

    How To Use µhtml

    Install the module via npm i uhtml and consume it like so:

    import {render, html, svg} from 'uhtml';
    // const {render, html, svg} = require('uhtml');
    
    render(document.body, html`<h1>Hello 👋 µhtml</h1>`);

    Alternatively you can use a CDN such as unpkg, as shown in this demo.

    <script src="https://unpkg.com/uhtml">/* global uhtml */</script>
    <!-- or -->
    <script type="module">
    import {render, html, svg} from 'https://unpkg.com/uhtml?module';
    </script>

    API Documentation

    Most information about µhtml is written in the documentation file, but the following gives essential details.

    API Summary

    The module exports the following functionalities:

    • a render(where, what) function to populate the where DOM node with what content, which can be a DOM node, or the return value of html and svg tags. The render function returns the where DOM node itself.
    • an html template literal tag, to produce any sort of HTML content.
    • an svg template literal tag, to produce any sort of SVG content.
    • both html and svg implement a .for(reference[, id]) template tag function for keyed weak relationships within the node. Please don't overuse this feature, as 90% of the time is not necessary, and it could make the rendering slower than it should be. Also, consider the ref attribute, in case a reference to the current node is needed at any time.
    • both html and svg implement a .node template tag function for one-off HTML or SVG creation. Please don't use html.node one off nodes within render(...) calls, as this utility exists to help create fragments or nodes that should be manually added to the DOM, and not through render calls.
    About Attributes

    Any element can have one or more attributes, either interpolated or not.

    render(document.body, html`
      <div id="main"
            class=${`content ${extra}`}
            data-fancy=${fancy}>
        <p contenteditable=${editable}
            @click=${listener}
            onclick=${listener}
            class="${['container', 'user'].join(' ')}">
          Hello ${user.name}, feel free to edit this content.
        </p>
      </div>
    `);

    These are the rules to follow for attributes:

    • interpolated attributes don't require the usage of quotes, but these work either way. name=${value} is OK, and so is name="${value}" or even name='${value}'
    • you cannot have sparse attribute interpolations: always use one interpolation to define each attribute that needs one, but never write things like style="top:${x};left${y}" as the parser will simply break with the error bad template. Use template literals within interpolations, if you want to obtain the exact same result: style=${`top:${x};left${y}`}
    • if the passed value is null or undefined, the attribute will be removed. If the value is something else, it will be set as-is as the value. If the attribute was previously removed, the same attribute will be placed back again. If the value is the same as it was before, nothing happens
    • if the attribute name starts with on or @, as example, onclick=${...} or @click=${...}, it will be set as a listener. If the listener changes, the previous one will be automatically removed. If the listener is an Array like [listener, {once:true}], the second entry of the array will be used as the listener's options.
    • if the attribute starts with a . dot, as in .setter=${value}, the value will be passed directly to the element per each update. If such a value is a known setter, either native elements or defined via Custom Elements, the setter will be invoked per each update, even if the value is the same
    • new: if the attribute starts with a ? question mark, as in ?hidden=${value}, the value will be toggled, accordingly to its truthy or falsy, value.
    • if the attribute name is ref, as in ref=${object}, the object.current property will be assigned to the node, once this is rendered, and per each update. If a callback is passed instead, the callback will receive the node right away, similar to how React ref does. Please note that conditional renders will not cleanup the reference, if this is not assigned to the new node.
    • if the attribute name is aria, as in aria=${object}, aria attributes are applied to the node, including the role one.
    • if the attribute name is .dataset, as in .dataset=${object}, the node.dataset gets populated with all values.

    The following is an example of both the aria and data cases:

    // the aria special case
    html`<div aria=${{labelledBy: 'id', role: 'button'}} />`;
    //=> <div aria-labelledby="id" role="button"></div>
    
    // the data special case
    html`<div .dataset=${{key: 'value', otherKey: 'otherValue'}} />`;
    //=> <div data-key="value" data-other-key="otherValue"></div>
    About HTML/SVG Content

    It is possible to place interpolations within any kind of node, and together with text or other nodes too.

    render(document.body, html`
      <table>
        ${lines.map((text, i) => html`
          <tr><td>Row ${i} with text: ${text}</td></tr>
        `)}
      </table>
    `);

    There are only few exceptional nodes that do not allow sparse content within themselves:

    • <plaintext>${content}</plaintext>, deprecated, yet it cannot contain comments
    • <script>${content}</script>, it can contain comments, but only whole text can be replaced
    • <style>${content}</style>, it cannot contain comments
    • <textarea>${content}</textarea>, same as above
    • <title>${content}</title>, same as above
    • <xmp>${content}</xmp>, same as above

    The following is an example on how to populate these nodes (wrong + right way):

    // DON'T DO THIS
    render(document.body, html`
      <style>
        body { font-size: ${fontSize}; }
      </style>
      <textarea>
        Write here ${user.name}
      </textarea>
    `);
    
    // DO THIS INSTEAD
    render(document.body, html`
      <style>
      ${`
        body { font-size: ${fontSize}; }
      `}
      </style>
      <textarea>
      ${`
        Write here ${user.name}
      `}
      </textarea>
    `);

    Beside nodes where the content will inevitably be just text (e.g., as it is for style or textarea), every other interpolation can contain primitives as strings, numbers, booleans, or the returned value of html or svg, plus regular DOM nodes.

    The only special case are Array of either primitives, or returned values from html or svg.

    render(document.body, html`
      <ul>
        <li>This is ${'primitive'}</li>
        <li>This is joined as primitives: ${[1, 2, 3]}</li>
        ${lines.map((text, i) => html`
          <li>Row ${i} with content: ${text}</li>
        `)}
      </ul>
    `);
    About Rendering Content

    The second what argument of the render(where, what) signature can be either a function, whose return value will be used to populate the content, the result of html or svg tags, or a DOM node, so that it is possible to render within a render.

    const Button = selector => {
      const button = document.querySelector(selector);
      return count => render(button, html`Clicks: ${count}`);
    };
    
    const Clicker = selector => {
      const button = Button(selector);
      return function update(count) {
        return render(document.body, html`
          <div onclick=${() => update(++count)}>
            Click again:
            ${button(count)}
          </div>
        `);
      };
    }
    
    const clicker = Clicker('#btn-clicker');
    clicker(0);
    About keyed renders

    µhtml html and svg tags implement exactly the same API offered by lighterhtml.

    This means that both html.for(reference[, id]) and svg.for(reference[, id]) will weakly relate the node with the reference and an optional unique id, instead of using its internal auto-referenced algorithm.

    render(document.body, html`
      <ul>
        ${items.map(item => html.for(item)`
          <li>Keyed row with content: ${item.text}</li>
        `)}
      </ul>
    `);
    About data purity

    On more than one occasion developers got bitten by the fact µhtml can produce some cryptic error when null, or empty content is provided as interpolation/hole.

    The problem is pretty simple:

    • don't loop / pass data that should not be rendered
    • sanitize data upfront instead of expecting this library to magically understand where, and how, such data should not be rendered

    A basic example would be the following:

    const dirtyData = [
      {name: 'first'},
      null,
      {name: 'second'}
    ];
    
    render(document.body, html`
      <ul>
        ${dirtyData.map(item => {
          // ⚠ this should not happen in the first place!
          if (!item)
            return null;
          return html`<li>${item.name}</li>`;
        })}
      </ul>
    `);

    There are at least two workarounds to consider:

    • use data.filter(item => validate(item)).map(...)
    • return an actual node:
      if (!item)
        return html`<!--ignore-->`;

    Between these two workarounds, I believe the cleanest one is the former: sanitize data upfront!

    The benefits are:

    • there are no unnecessary nodes in the DOM
    • there are no weird cases to consider
    • the mapping is pure: data in, node out
    About Custom Elements

    Custom Elements are available either via µce (micro custom elements, a 3K library based on µhtml), or via vanilla JS, as demoed in WebComponents.dev.

    Compatibility

    This module works in IE11, Edge, and every other Desktop to Mobile browser, including KaiOS.


    µhtml vs lighterhtml

    You could read an exhaustive summary of features differences, but the first thing to keep in mind, is that lighterhtml is at par with uhtml features, but not vice-versa, meaning if you need anything more, you can always switch to lighterhtml later on, and without changing a single line of code.

    The following is a list of other points to consider when choosing µhtml over of lighterhtml (or vice-versa).

    Differences from lighterhtml
    • there are no sparse attributes, each attribute must have a single interpolated value: attribute=${value} is OK, attribute="${a}${b}" is not, and attribute="some ${'partial'}" is not allowed neither.
    • the interpolations are simple: primitive, or array of primitives, and nodes, or array of nodes.
    • the style attribute is not special at all: if you want to pass objects there, please transform these as you prefer.
    • the domdiff has been replaced with udomdiff, with a new blazing fast and super small diffing algorithm written from scratch
    • the template argument is not normalized. If you target browsers with issue with such argument, please be sure you transpile your code with latest Babel before shipping to production
    • no domtagger whatsoever, you can't change the current behavior of the library in any way
    Similar or better than lighterhtml
    • uhtml should not suffer any of the IE11/Edge issues, or invalid SVG attributes warnings, as the parsing is done differently 🎉
    • nested html and svg are allowed like in lighterhtml. The version 0 of this library didn't allow that, hence it was more "surprise prone". uhtml in that sense is more like a drop-in replacement for lighterhtml, and vice-versa
    • keyed results via htmlfor(...) or svg.for(...), as well as one-off node creation, via html.node or svg.node are the same found in lighterhtml
    • both aria=${object}, and ref=${...} special attributes work same as lighterhtml
    • the .dataset=${object} helper works the same as lighterhtml
    • the .property=${...} direct setter is still available
    • self closing nodes are also supported, go wild with <custom-elements /> or even <span />
    • the wire parsing logic has been simplified even more, resulting in slightly better bootstrap and update performance
    • it's half the production size of lighterhtml, mostly because ...
    • there are no 3rd party dependencies, except for µparser, µdomdiff, and for @ungap/create-content, needed only for IE11, but removable via @ungap/degap, same way I've done it here, or babel-plugin-remove-ungap. The compressed final size difference is just around ~0.2K though.
    µhtml library goals
    • be an essential/ideal companion for wickedElements, hookedElements, or any third party that would like a lighterhtml like API, without the extra weight
    • keep it as simple as possible, but not simpler
    • see if there is room for improvements in lighterhtml whenever uhtml simplifications allow to be ported there

    V2 Breaking Change

    The recently introduced data helper could conflict with some node such as <object>, hence it has been replaced by the .dataset utility. Since element.dataset = object is an invalid operation, the sugar to simplify data- attributes is now never ambiguous and future-proof: <element .dataset=${...} /> it is.

    Install

    npm i uhtml

    DownloadsWeekly Downloads

    3,042

    Version

    3.1.0

    License

    ISC

    Unpacked Size

    157 kB

    Total Files

    27

    Last publish

    Collaborators

    • webreflection