trans-render

trans-render (abbreviation: TR) provides a methodical way of instantiating a template. It draws inspiration from the (least) popular features of XSLT. Like XSLT, TR performs transforms on elements by matching tests on elements. Whereas XSLT uses XPath for its tests, tr uses css path tests via the element.matches() and element.querySelector() methods. Unlike XSLT, though, the transform is defined with JavaScript, adhering to JSON-like declarative constraints as much as possible.

XSLT can take pure XML with no formatting instructions as its input. Generally speaking, the XML that XSLT acts on isn't a bunch of semantically meaningless div tags, but rather a nice semantic document, whose intrinsic structure is enough to go on, in order to formulate a "transform" that doesn't feel like a hack.

Likewise, with the advent of custom elements, the template markup will tend to be much more semantic, like XML. trans-render's usefulness grows as a result of the increasingly semantic nature of the template markup, because often the markup semantics provide enough clues on how to fill in the needed "potholes," like textContent and property setting, without the need for custom markup, like binding attributes. But trans-render is completely extensible, so it can certainly accommodate custom binding attributes by using additional, optional helper libraries.

This can leave the template markup quite pristine, but it does mean that the separation between the template and the binding instructions will tend to require looking in two places, rather than one. And if the template document structure changes, separate adjustments may be needed to keep the binding rules in sync. Much like how separate style rules often need adjusting when the document structure changes.

Advantages

TR will certainly take advantage of phase I of template instantiation when it's available. TR sees itself as either an alternative, or a supplement, to any kind of inline binding future phases of template instantiation support.

By keeping the binding separate, the same template can thus be used to bind with different object structures.

Providing the binding transform in JS form inside the transform function signature has the advantage that one can benefit from TypeScript typing of Custom and Native DOM elements with no additional IDE support. As much as possible, JSON-like structures are also used, allowing most or all of the binding to remain declarative.

Another advantage of separating the binding like this is that one can insert comments, console.log's and/or breakpoints, making it easier to walk through the binding process.

For more musings on the question of what is this good for, please see the rambling section below.

NB It's come to my attention (via template discussions found here) that there are some existing libraries which have explored similar ideas:

1. pure-js
2. weld

Workflow

trans-render provides helper functions for either 1) cloning a template, and then walking through the DOM, applying rules in document order, or, 2) using the same syntax, applying changes on a live DOM fragment. Note that the document can grow as processing takes place (due, for example, to cloning sub templates). It's critical, therefore, that the processing occur in a logical order, and that order is down the document tree. That way it is fine to append nodes before continuing processing.

As such, trans-render could (in theory) be used to augment/finesse the results of template.createInstance of the template instantiation proposal.

Drilling down to children

For each matching element, after modifying the node, you can instruct the processor which node(s) to consider next.

Most of the time, especially during initial development, you won't need / want to be so precise about where to go next. Generally, the pattern, as we will see, is just to define transform rules that match the HTML Template document structure pretty closely.

So, in the example we will see below, this notation:

const Transform = {
    details: {
        summary: 'Hallå'
    }
};

means "if a node has tag name 'details', then find any direct children of the details tag that has tag name 'summary', and set its textContent property to 'Hallå'." Let's show the full syntax for a minimal working example:

Syntax Example:

<template id="sourceTemplate">
    <details>
        ...
        <summary>E pluribus unum</summary>
        ...
    </details>
</template>
<div id="target"></div>
<script type="module">
    import { transform } from 'trans-render/transform.js';
    const model = {
        summaryText: 'hello'
    }
    const Transform = {
        details: {
            summary: model.summaryText
        }
    };
    transform(sourceTemplate, { Transform }, target);
</script>

Produces

<div id="target">
    <details>
        ...
        <summary>hello</summary>
        ...
    </details>
</div>

Not limited to declarative syntax

The transform example so far has been declarative (according to my definition of that subjective term). This library is striving to make the syntax as declarative as possible as more functionality is added. The goal being that ultimately much of what one needs with normal UI development could in fact be encoded into a separate JSON import.

However, bear in mind that the transform rules also provide support for 100% no-holds-barred non-declarative code:

const Transform = {
    details:{
        summary: ({target}: RenderContext<HTMLSummaryElement>) => {
            ///knock yourself out
            target.appendChild(document.body);
        }
    }
}

Template Stamping

If using trans-rendering for a web component, you will very likely find it convenient to "stamp" a significant number of individual elements of interest. The quickest way to do this is via the templStamp plugin:

import {templStampSym} from 'trans-render/plugins/templStamp.js';
...
const uiRefs = {mySpecialElement1: Symbol(), mySpecialElement2: Symbol()};
const Transform = {
    ':host': [templStampSym, uiRefs]
}

This will search the template / DOM fragment / matching target for all elements whose id or "part" attribute is "mySpecialElement1" or "mySpecialElement2". Only one element will get stamped for each reference later. In other words, stamping is only useful if you have exactly one element whose id or part is equal to "mySpecialElement1".

A reassessment of this functionality will take place with the advent of DOM Parts.

Here we also see the concept of being able to extend the trans-render library, while sticking to quite strict declarative syntax.

const Transform = {
    ':host': [templStampSym, uiRefs]
}

Syntax summary

We'll be walking through a number of more complex scenarios, but for reference, the rules are available below in summary form, if you expand the section.

They will make more sense after walking through examples, and, of course, real-world practice.

const Transform = {
    details: {
        summary: model.summaryText
    }
};

const Transform = {
    'details': {
        'summary': model.summaryText
    }
};

Multiple matching with "Ditto" notation

Sometimes, one rule will cause the target to get (new) children. We then want to apply another rule to process the target element, now that the children are there.

But uniqueness of the keys of the JSON-like structure we are using prevents us from listing the same match expression twice.

We can specify multiple matches as follows:

import { transform } from '../transform.js';
const Transform = {
    details: {
        article: articleTemplate,
        '"': ({target}) => ...,
        '""': ...,
        '"3': ...
    }
};
transform(sourceTemplate, { Transform }, target);

I.e. any selector that starts with a double quote (") will use the last selector that didn't.

Simple Template Insertion

A template can be inserted directly inside the target element as follows:

<template id="summaryTemplate">
My summary Text
</template>
<template id="sourceTemplate">
    <details>
        ...
        <summary></summary>
        ...
    </details>
</template>
<div id="target"></div>
<script type="module">
    import { transform } from '../transform.js';
    const Transform = {
        details: {
            summary: summaryTemplate
        }
    };
    transform(sourceTemplate, { Transform }, target);
</script>

Here we are relying on the fact that outside any Shadow DOM, id's become global constants. So for simple HTML pages, this works. Assuming HTML Modules someday bring the world back into balance, an open question remains how code will be able to reference templates defined within the HTML module.

For now, typically, web components are written in JavaScript exclusively. Although creating a template is one or two lines of code, the code is a bit lengthy, so a utility to create a template is provided that can then be referenced. This allows the repetitive, scandalous code, required in lieu of an HTML Template DOM node, to be hidden from view.

If you don't use shadowed template insertion or slotted template insertion mentioned below, then the way the template cloning works is this:

1. Cloned content is inserted inside a tag called template-content.
2. Attribute 'part=content' is added to the template-content tag.
3. Old matching template-content's are hidden rather than deleted, via display: none, and attribute part=content is removed.

These observations are important if you plan to do some node matching on the (newly) created content.

You will need to add a rule that looks something like:

const Transform = {
    details: {
        summary: summaryTemplate,
        '"':{
            contentPart:{
                ...
            }
        }
    }
};

Shadowed Template Insertion

<template id="articleTemplate" data-shadow-root="open">
    <slot name="adInsert"></slot>
My interesting article...
</template>
<template id="sourceTemplate">
    <details>
        ...
        <summary></summary>
        <article>
            <iframe slot=adInsert></iframe>
        </article>
        ...
    </details>
</template>
<div id="target"></div>
<script type="module">
    import { init } from '../init.js';
    const Transform = {
        details: {
            article: articleTemplate
        }
    };
    init(sourceTemplate, { Transform }, target);
</script>

When ShadowRoot is attached to the article element, the children can then be slotted into the ShadowDOM, which is quite convenient.

Limited support for Slotted content when not using ShadowDOM (WIP)

It is unfortunate that use of slots is tightly coupled with ShadowDOM, when it comes to native support. Vue.js and Svelte appear to demonstrate that the slot concept is useful beyond ShadowDOM support.

TR supports limited slot support outside the bounds of ShadowDOM. For now the only support is this:

If template insertion (mentioned above) is applied to an element that already has children, and if the inserted template has at least one slot element, the original children replace the slot elements, based on similar (first order) rules to Shadow DOM slotting. A slot with attribute "as-template" will be converted to a template element.

This can be quite useful in converting compact loop syntax into clunkier markup that a web component may require:

<template id=repeatTemplate>
    <my-repeater-element>
        <slot as-template></slot>
    </my-repeater-element>
</template>

<template id=mainTemplate>
    <ul>
        <li foreach item in items>
            <span data-field=item.name></span>
        </li>
    </ul>
</template>
<script>
const Transform = {
    ':has(> [foreach])': repeatTemplate
}
</script>

produces:

<ul>
    <my-repeater-element>
        <template>
            <li foreach item in items>
                <span data-field=item.name></span>
            </li>
        </template>
    </my-repeater-element>
</ul>

Unlike the more powerful native ShadowDOM, once the children are merged into the slots, there's no longer a distinction between light children and shadow children. So non-shadow slotting makes the most sense when used during the init transform.

Arbitrary queries.

If most of the template is static, but there's an isolated, deeply nested element that needs modifying, it is possible to drill straight down to that element by specifying a "Select" string value, which invokes querySelector. But beware: there's no going back to previous elements once that's done (within that nested transform structure).

Jumping arbitrarily down the document tree can be done with a "NextStep" object:

const Transform = {
    article: {
        Select: 'footer',
        Transform: {
            'p.contact': model.author.email
        }

    }
};

In the example above, when the transformer encounters an article tag, it will then do a querySelect for the first element matching "footer".

It then checks within the direct children of footer for elements matching css selector "p.contact". If such an element is found, then the textContent is set to model.author.email (where "model" is assumed to be some object in scope).

The object:

{
    Select: ...
    Transform: ...
}

is a "NextStep" object, and can be easily distinguished from a nested transform object with CSS selector keys (as the previous examples showed) by the presence of capital letters for the keys. The options of the NextStep object are as shown:

export interface NextStep {
    Transform?: TransformRules,
    NextMatch?: string,
    Select?: TransformRules | null,
    MergeTransforms?: boolean,
    SkipSibs?: boolean,
}

Matching next siblings

We most likely will also want to check the next siblings down for matches. Previously, in order to do this, you had to make sure "matchNextSibling" was passed back for every match. But that proved cumbersome. The current implementation checks for matches on the next sibling(s) by default. You can halt going any further by specifying "SkipSibs" in the "NextStep" object discussed above, something to strongly consider when looking for optimization opportunities.

It is deeply unfortunate that the DOM Query Api doesn't provide a convenience function for finding the next sibling that matches a query, similar to querySelector or closest. Just saying. But some support for "cutting to the chase" laterally is also provided, via the "NextMatch" property in the NextStep object.

Matching everything

Note the transform rule:

Transform: {
    '*': {
        Select: '*'
    },

The expression "*" is a match for all HTML elements. What this is saying is "for any element regardless of css-matching characteristics, continue processing its first child (Select => querySelector('*')). This, combined with the default setting to match all the next siblings means that for a "sparse" template with very few pockets of dynamic data, you will be doing a lot more element matching than needed, as every single HTMLElement node will be checked for a match. But for initial, pre-optimization work, this transform rule can be a convenient way to get things done more quickly.

If you use a rule like the one above, then the other selector rules will almost exactly match what you would expect with a classic css file. In the absense of such a rule, css selectors will flow most naturally if emulating the nested support provided by tools such as SASS.

At this point, only a synchronous workflow is provided (except when piercing into ShadowDOM).

What does wdwsf stand for?

As you may have noticed, some abbreviations are used by this library:

• init = initialize
• ctx = (rendering) context
• idx = (numeric) index of array
• SkipSibs = Skip Siblings
• attribs = attributes
• props = properties
• refs = references

The ctx object has a "mode" property that becomes "update" after the initial transform completes.

Use Case 1: Applying the DRY principle to (post) punk rock lyrics

Example 1a

Demo

Demonstrates including sub templates.

Example 1b

Demo

Demonstrates use of update, rudimentary interpolation, recursive select.

Conditional Display

Permanent Removal

If a matching node returns a boolean value of false, the node is removed. For example:

...
"section[data-type='attributes']":false
...

Here the tag "section" will be removed.

NB: Be careful when using this technique. Once a node is removed, there's no going back -- it will no longer match any css if you use trans-render updating (discussed below). If your use of trans-render is mostly to display something once, and you recreate everything from scratch when your model changes, that's fine. However, if you want to apply incremental updates, and need to display content conditionally, it would be better to either use a custom element for that purpose, or utilize the conditional template support shown below.

Lazy loading (and limited support for conditional display)

article: [isHotOutside, warmWeatherTemplate,, coldWeatherTemplate]

You can also do different sub transforms within the article element:

article: [isHotOutside, warmWeatherTransform,, coldWeatherTransform]

The missing element, after the warmWeather[Template|Transform], allows for a choice of reference symbols to be established for the target element (article in this case),

Property / attribute / event binding

import { transform} from '../transform.js';
const Transform = {
    details: {
        'my-custom-element': [ //Hi!
            //Prop Setting
            {prop1:{greeting: 'hello'}, prop2:'hello', },
            //Event Handler Setting
            {click: this.clickHandler},
            //Attribute Setting
            {'my-attribute': 'myValue', 'my-attribute2': true, 'my-old-attribute': null}, // null removes attribute
            //Transform or NextStep Object
            {
                'my-light-child': ...
            }
        ]
    }
};
transform(sourceTemplate, { Transform }, target);

Here, 'my-custom-element' is a custom element, and the array starting with [ //Hi! it matches to is treated as a tuple (and tuple support in JS and TypeScript seems to be gaining momentum). An easy to remember trick for this particular Tuple is: "PEAT", which stands for prop setting, event handler setting, attribute setting, transform.

The first element of the tuple must be a JS Object, not undefined or null. I.e. if it is undefined, the rest of the array will be ignored.

Tip: If the first element of the tuple binds to some optional property, which might be undefined or null, you can ensure that the array be treated as a "PEAT" array by adding a union with an empty {}. I.e.

const settings = {...}
const Transform = {
    'my-custom-element':[settings.somePropThatMightBeUndefined || {}]
}

Although the first element of the tuple can't be undefined, each of the renaming elements of the tuple are "optional" in the sense that you can either end the array early, or you can skip over one or more of the settings by specifying an empty object ({}), or just a comma i.e. [{},,{'my-attribute', 'myValue'}].

A suggestion for remembering the order these "arguments" come in -- Properties / Events / Attributes / Transform can be abbreviated as "PEAT." Actually, there is a fifth "argument" of type symbol, which stores the target in ctx.host. So the acronym to remember is really PEATS.

The second element of the array, where event handlers can go, can actually pass arguments to the handler:

{click: [this.selectNewKey, val: 'dataset.keyName']}

which could allow the event handler to actually be a regular method expecting a parameter.

class MyCustomElement extends XtalElement{
    selectNewKey(key: string){
        ...
    }
}

In this case, it would be a string parameter, since target.dataset.keyName will be of type script. val supports a simple a.b.c type expressions, read fro the current matching target element. The actual event object is still available as the second parameter of the method.

If a third argument is provided, it is assumed to be a function which does some kind of conversion of the value extracted from the target:

{click: [this.setAge, val: 'dataset.age', parseInt]}

class MyCustomElement extends XtalElement{
    setAge(age: number){
        ...
    }
}

A more verbose but somewhat more powerful way of setting properties on an element is discussed with the decorate function discussed later.

Prop setting shortcut [No test coverage]

We mentioned earlier that if a css match maps to a string, we do the most likely thing one would want -- setting the textContent:

const Transform = {
    details: {
        summary: 'Hallå'
    }
};

But it is also desirable to have a fast way of setting properties with few required keystrokes.

This can be done as follows.

If the template contains this markup, with a "pseudo" attribute starting with a dash:

<template>
    <my-custom-element -my-prop></my-custom-element>
</template>

const Transform = {
    'my-custom-element[-my-prop]':{
        subProp1: 'hello',
        subProp2: 'world'
    }
}

Then the property "myProp" of the my-custom-element instance will be set to {subProp1:'hello', subProp2: 'world'}.

In addition to the slightly less typing required to set property values, there is also the advantage that the template provides fairly non-obtrusive clues in the markup as to what is happening.

Contextual, Synchronous Evaluation

All of the rules listed above also apply to the result of evaluating a lambda expression:

const Transform = {
    details: {
        summary: ({ctx}) => ctx.summaryText
    }
}

ctx is an object meant to pass data through (repeated, nested) transforms. It includes a number of internal, reserved properties.

TypeScript Tip: Some of the properties of ctx, like target, are quite generic (e.g. target:HTMLElement, item: any). But one can add more specific typing thusly:

summary: ({target, item} :  {target: HTMLInputElement, viewModel: MyModel, item: MyModelItem}) =>{
    ...
}

The argument is of type "RenderContext" so you can also get the benefit of typing thusly:

    summary: ({target, item} :  RenderContext<HTMLInputElement, MyModelItem>) =>{
        ...
    }

Planting flags

It was mentioned earlier that there is a plugin, templStamp, that can map large swaths of uniquely named (via id or part attribute) elements to symbols for later use.

This can alo be done on an individual element basis, with no plugin required:

    const myFastAccessSymbol = Symbol();

    initTransform = {
        'my-rapidly-changing-element': myFastAccessSymbol
    }

    updateTransforms = [{
        ({fastChangingProp}) =>{
            [myFastAccessSymbol]: ({target}) => target.myProp = fastChangingProp
        }
    }]

Multiple matching with "More" symbol [TODO: No Test coverage]

Previously, we provided a strategy for matching duplicate css selectors, using "ditto" notation. But what about symbol keys? That won't work.

Instead, do the following:

import {transform, more} from 'trans-render/transform.js';

...
updateTransform = {
    [mySymbol]: [do something],
    [more]:{
        [mySymbol]: [do something else]
    }
}

Replacing / inserting tags declaratively

One functionality that trans-render considers of utmost importance is the ability dynamically replace one tag with another elegantly.

Examples of where tag substitution is useful are:

1. Cases where "polymorphism" between a similar family of tags is required.
2. Extending basic functionality, using built-in native HTML elements, with more functional, visually appealing design libraries.
3. Using version specific custom elements, in a micro-front-end environment (i.e. supporting parallel versions).

This is best done before a template's clone has been inserted into the live DOM tree, but trans-render imposes no rules on when it can be done.

Example syntax:

const initTransform = {
    ...
    'my-element': [MyElement.isReally, 'replace'], 
    ...
}

In addition to replacing a tag, you can instead insert a tag, and specify the location relative to the target. E.g.:

const initTransform = {
    ...
    details: ['summary', 'afterBegin'],
    '"':{
        summary:'Summary text'
    }
    ...
}

Utility functions

Create template element programmatically

createTemplate(html: string, context?: any, symbol?: symbol)

Example:

    details: ({ctx}) => createTemplate(`<summary>SummaryText</summary>...`, ctx);

An explanation for the second and third parameters is needed.

Templates shine most when they are created once, and cloned repeatedly as needed. What this means, in the context of a JS module, is that they should be cached somewhere, and instances cloned from the cache. The use of the third parameter, symbol, ensures that no two disparate code snippets will trample over each other. But which "cache" to use? The easiest, sledgehammer approach would be to cache it in self or globalThis. But there is likely a cost to caching lots of things in such a global area, as the lookups are likely to grow (logarithmically perhaps).

Caching inside the renderContext object (ctx) may be too tepid, because the renderContext is likely to be created with each instance of a web component.

So the code checks whether the context object has a "cache" property, and if so, it caches it there. If using this library inside a web component library, a suggestion would be to set ctx.cache = MyCustomElementClass.

Simple Loop support

Imperative Repeat

repeat(
    template: HTMLTemplateElement | [symbol, string], 
    ctx: RenderContext, 
    countOrItems: number | any[], 
    target: HTMLElement, 
    initTransform: TransformValueOptions,
    updateTransform: TransformValueOptions = initTransform
)

The next big use case for this library is using it in conjunction with a virtual scroller. As far as I can see, the performance of this library should work quite well in that scenario.

However, no self respecting rendering library would be complete without some internal support for repeating lists. This library is no exception. While the performance of the initial list is likely to be acceptable, no effort has yet been made to utilize state of the art tricks to make list updates keep the number of DOM changes at a minimum.

Anyway the syntax is shown below. What's notable is a sub template is cloned repeatedly, then populated using the simple init / update methods.

<div>
    <template id="itemTemplate">
        <li></li>
    </template>
    <template id="list">
        <ul id="container"></ul>
        <button id="addItems">Add items</button>
        <button id="removeItems">Remove items</button>
    </template>
    <div id="target"></div>

    <script type="module">
    import { init } from '../init.js';
    import { repeat } from '../repeat.js';
    import { update } from '../update.js';
    const options = {matchNext: true};
    const itemTransform = {
        li: ({ item }) => 'Hello ' + item.name,
    };
    const ctx = init(list, {
        Transform: {
            ul: ({ target, ctx }) =>  repeat(itemTemplate, ctx, 10, target, itemTransform) // or repeat(itemTemplate, ctx, items, target, itemTransform) 
        }
    }, target, options);
    ctx.update = update;
    addItems.addEventListener('click', e => {
        repeat(itemTemplate, ctx, , container, itemTransform); 
    });
    removeItems.addEventListener('click', e =>{
        repeat(itemTemplate, ctx, 5, container);
    })
    </script>
</div>

Declarative Repeat

Please expand below

    const ctx = init(list, {
        Transform: {
            ul: [items, itemTemplate, [3, 10], itemTransform,,, ul$]
        }
    }, target, options);

interface ItemStatus{
    version: number | string;
    breaking: boolean;
    inScope: boolean;
    identity: number | string;
}
LoganLoop(
    template: HTMLTemplateElement | [symbol, string], 
    ctx: RenderContext, 
    items: any[],
    itemStatus: item: any => ItemStatus, 
    target: HTMLElement, 
    initTransform: TransformValueOptions,
    updateTransform: TransformValueOptions = initTransform
)

<ul>
    <my-repeater-element>
        <template>
            <li>{item.name}</li>
        </template>
    </my-repeater-element>
</ul>

<ul>
    <proxy-props for=for items={model.items}></proxy-props>
    <template be-for>
        <li>{item.name}</li>
    </template>
</ul>

<ul>
    <template be-for='{
        "items": [{"name":"fergie"},{"name":"will.i.am"}]}
        "transform": {"li": "ctx.item.name"}
    '}>
        <li></li>
    </template>
</ul>

<ul>
    <li foreach item in items>
        <span data-field=item.name><span>
    </li>
</ul>

<ul>
    <my-repeater-element collection-name=items>
        <template>
            <li foreach item in items>
                <span data-field=item.name><span>
            </li>
        </template>
    </my-repeater-element>
</ul>

const trePatternTransformer = ({for, inner}) => /* html */`
    <my-repeater-element -items>
        <template>
            ${inner}
        </template>
    </my-repeater-element>
`;

Adjacent template insertion

insertAdjacentTemplate(template: HTMLTemplateElement, target: Element, position: InsertPosition)

This function is modeled after insertAdjacentElement / insertAdjacentHTML. Only here we are able to insert a template. By using the preferred "afterEnd" as the insert position, the trans-rendering will be able to process those nodes like any other nodes.

Ergonomic Tag Creation

appendTag<T extends HTMLElement>(container: HTMLElement, name: string, config: PEAUnionSettings<T> | DecorateArgs<T> /* untested */) : HTMLElement 

Just saves a tiny bit of boiler plate (document.createElement, container.appendChild)

Text Searching

split(target: HTMLElement, textContent: string, search: string | null | undefined)

Splits text based on search into styleable spans with class "match" and sets the innerHTML to this partitioned content. The second argument, 'textContent' should not contain any HTML tags in it (but that is left to the caller to ensure).

Content Swapping, Part I

replaceElementWithTemplate(target: HTMLElement, ctx: RenderContext, template: HTMLTemplateElement | [symbol, string]) 

During pipeline processing, replace a tag with a template. The original tag goes into ctx.replacedElement.

For the template parameter, you can either pass in a template object, or an html string / symbol pair. The symbol is required so the template can be cached.

Content Swapping, Part II

replaceTargetWithTag<TargetType extends HTMLElement = HTMLElement, ReplacingTagType extends HTMLElement = HTMLElement>
    (target: TargetType, ctx: RenderContext, tag: string, preSwapCallback?: (el: ReplacingTagType) => void)

During pipeline processing, replace a tag with another tag. The original tag goes into ctx.replacedElement

Piercing into ShadowDOM

pierce<TargetType extends HTMLElement = HTMLElement>(el: TargetType, ctx: RenderContext, targetTransform: TransformRules)

... pierces into the shadow root of the target element, and (asynchronously) applies transform rules within the shadow root. If the target element is a custom element, there is a delay to wait for the custom element to be upgraded, but there is perhaps a bit of timing fragility that accompanies this dangerous (but necessary as a last resort) function.

NB Doing this breaks any and all warranties from the component / template being surgically altered.

export function domMerge<(target: HTMLElement, vals: Vals): void

export interface Vals {
  attribs?: { [key: string]: string | boolean | number };
  propVals?: object;
}

export function decorate(
  target: HTMLElement,
  source: DecorateArgs
)

export interface DecorateArgs extends Vals{
    propDefs?: object,
    methods?: {[key: string] : Function},
    on?: {[key: string] : (e: Event) => void},
}

<div id="decorateTest">
    <button>Test</button>
</div>
<script type="module">
    import {decorate} from '../decorate.js';
    import {init, attribs} from '../init.js';
    init(decorateTest, {
        Transform: {
            div: {
                button: ({target}) => decorate(target, {
                    propVals:{
                        textContent: 'Hello',
                    },
                    attribs: {
                        title: 'Hello, world'
                    },
                    propDefs:{
                        count: 0
                    },
                    on:{
                        click: function(e){
                            this.count++;
                        }
                    },
                    methods:{
                        onPropsChange(){
                            alert(this.count)
                        }
                    }
                })
            }
        }            
    })
</script>

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Document</title>
</head>
<body>
    <div id="decorateTest">
        <button>Test</button>
    </div>
    <script type="module">
        import {decorate, attribs} from '../decorate.js';
        import {init} from '../init.js';
        const count = Symbol('count');
        const myMethod = Symbol('myMethod');
        init(decorateTest, {
            Transform: {
                button: ({target}) => decorate(target, {
                    propVals:{
                        textContent: 'Hello',
                    },
                    attribs:{
                        title: "Hello, world"
                    }, 
                    propDefs:{
                        [count]: 0
                    },
                    on:{
                        click: function(e){
                            this[count]++;
                        }
                    },
                    methods:{
                        onPropsChange(){
                            this[myMethod]();
                        },
                        [myMethod](){
                            alert(this[count]);
                        }
                    }
                })
            }
            
            
        })
    </script>
</body>
</html>

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Document</title>
</head>
<body>
    <div id="decorateTest">
        <button>Test</button>
    </div>
    <script type="module">
        import {decorate} from '../decorate.js';
        import {init} from '../init.js';
        init(decorateTest, {
            symbols: {
                count: Symbol('count'),
                myMethod: Symbol('myMethod')
            },
            Transform: {
                button: ({target, ctx}) => decorate(target, {
                    propVals: {
                        textContent: 'Hello',
                    },
                    attribs:{
                            title: "Hello, world"
                    },
                    propDefs:{
                        [ctx.symbols['count']]: 0
                    },
                    on:{
                        click: function(e){
                            this[ctx.symbols['count']]++;
                        }
                    },
                    methods:{
                        onPropsChange(){
                            this[ctx.symbols['myMethod']]();
                        },
                        [ctx.symbols['myMethod']](){
                            alert(this[ctx.symbols['count']]);
                        }
                    }
                })
            }
        })
    </script>
</body>
</html>

Ramblings From the Department of Faulty Analogies

When defining an HTML based user interface, the question arises whether styles should be inlined in the markup or kept separate in style tags and/or CSS files.

The ability to keep the styles separate from the HTML does not invalidate support for inline styles. The browser supports both, and probably always will.

Likewise, arguing for the benefits of this library is not in any way meant to disparage the usefulness of the current prevailing orthodoxy of including the binding / formatting instructions in the markup. I would be delighted to see the template instantiation proposal, with support for inline binding, added to the arsenal of tools developers could use. Should that proposal come to fruition, this library could be used to augment the native template instantiation process.

And in fact, the library described here is quite open ended. Until template instantiation becomes built into the browser, this library could be used as a stand-in. Once template instantiation is built into the browser, this library's scope could reduce, but could continue to supplement the native support when needed.

For example, in the second example above, the core "init" function described here has nothing special to offer in terms of string interpolation, since CSS matching provides no help:

<div>Hello {{Name}}</div>

We provide a small helper function "interpolate" for this purpose, but as this is a fundamental use case for template instantiation, and as this library doesn't add much "value-add" for that use case, native template instantiation could be used as a first round of processing. And where it makes sense to tightly couple the binding to the template, use it there as well, followed by a binding step using this library. Just as use of inline styles, supplemented by css style tags/files (or the other way around) is something seen quite often.

A question in my mind, is how does this rendering approach fit in with web components (I'm going to take a leap here and assume that HTML Modules / Imports in some form makes it into browsers, even though I think the discussion still has some relevance without that).

I think this alternative approach can provide value, by providing a process for "Pipeline Rendering": Rendering starts with an HTML template element, which produces transformed markup using TR or (hopefully soon) native template instantiation. Then consuming / extending web components could insert additional bindings via the CSS-matching transformations this library provides.

To aid with this process, the transform function provides a rendering options parameter, which contains an optional "initializedCallback" and "updatedCallback" option. This allows a pipeline processing sequence to be set up, similar in concept to Apache Cocoon.

Client-side JS faster than SSR?

Another interesting case to consider is this Periodic Table Codepen example. Being what it is, it is no surprise that there's a lot of repetitive HTML markup needed to define the table.

An intriguing question, is this: Could this be the first known scenario in the history of the planet, where rendering time (including first paint) would be improved rather than degraded with the help of client-side JavaScript?

The proper, natural instinct of a good modern developer, including the author of the codepen, is to generate the HTML from a concise data format using a server-side language (pug).

But using this library, and cloning some repetitive templates on the client side, reduces download size from 16kb to 14kb, and may improve other performance metrics as well. These are the performance results my copy of chrome captures, after opening in an incognito window, and throttling cpu to 6x and slow 3g network.

Trans-Rendering:

Original:

You can compare the two here: This link uses client-side trans-rendering. This link uses all static html

Results are a bit unpredictable, and usually the differences are less dramatic.

Lighthouse scores also provide evidence that trans-rendering improves performance.

Trans-Rendering:

Original:

Once in a while the scores match, but most of the time the scores above are what is seen.

So the difference isn't dramatic, but it is statistically significant, in my opinion.

See this side-by-side comparison for more evidence of the benefits.

trans-render the web component

A web component wrapper around the functions described here is available.

Example syntax

Demo

If you are here what appears next should work: