DOM Templating API Explainer

[keithamus]

@justinfagnani proposed the DOM Templating API explainer.

I think it would be good for us to discuss this, how well does it fit frameworks, is it something they could reasonably use? Would it lower complexity of frameworks if this existed in the Web Platform?

[WebReflection]

that proposal has been around for a while and my current take is that it'd be better than nothing but it's basically lit-html semantics and while that's not necessarily a bad thing, there are 2 major points I keep discussing:

1. it's not possible to set event listeners/handlers options, solved in uhtml via @scroll=${[handler, { passive: true }]}. I am not saying uhtml idea is the best one one could imagine but options for events are mandatory in some case and there's nothing in there about that (or I've missed it)
2. partial attributes and attributes maybe quoted and maybe not are footgun prone:
   1. an attribute can only have a single value at the time
   2. 2 or more signals to update twice the same attribute instead of a single computed is performance hostile
   3. too many distinctions between an attribute part, an attribute whole thing (which I am not sure how should be handled, it feels like half JSX <Comp {...props} /> idea/based thing

To me attributes should be kept simple and throw at the very beginning so that there will be room for improvements, that means only <el attr=${value}></el> with optional ?, . and @ prefix should be valid (ok, the quotes could be relaxed but then we enter <el attr=" ${value} "></el> case that will require answers such as "where those leading and ending spaces meant?" and so on) and not much else.

Everything else feels like awesome, if native/backed in, yet the industry kept using JSX or Svelte or ... tools so this might be too little, too late yet I am sure more people will be interested in using this instead of requiring mandatory heavy and non-standard toolchains to produce reactive layouts.

That's it from me and thanks for opening this discussion 👋

edit

P.S. the hydration story is what makes this proposal extremely interesting because that's a badly solved problem with most frameworks out there ... if we nail that bit I think the whole Web will benefit from this proposal. If we focus only on client-side effects people can keep using lit or similar variants.

[justinfagnani]

lit-html was in large part inspired by and designed to be compatible with the ideas Apple and Google developed as part of the Template Instantiation proposal, and lit-html was specifically designed to be the shape of an API that could be adopted by the platform. So yes, this proposal looks a lot like lit-html because lit-html is essentially a polyfill for these ideas.

• Event listener options: It is possible to allow them to be set. We can just read the options off the object passed to the binding. The is what lit-html does. I'll open an issue for that.
• Ergonomically, developers expect to be able to bind to part of an attribute, like <img src="/images/${category}/${name}">. I strongly believe this API should be ergonomic.
• Hydration isn't yet addressed in the proposal, but the more recent work on DOM Parts and Processing Instructions from some Google teams points in the direction: a set of PIs for serializing parts, an API for getting those parts, and an API for applying a template result to existing DOM while preserving the existing parts.

[WebReflection]

thanks for clarifying lit story and intents, about the rest:

• in uhtml the contract is simple, @click=${() => {}} or @click=${{handleEvent(){}}} for listeners when one argument is meant, [listener, options] when more than argument is meant at addEventListener intent. If lit accepts objects to crawl for options that feels possibly problematic or conflicting with an otherwise object shape, as in {options:[],handleEvent(){}} so I am curious to learn how's that solved
• ergonomically speaking, JSX doesn't accept partial props/attributes and that didn't stop JSX from being the most widely adopted non-standard solution for HTML templates. <Comp prop={value} /> is the only acceptable way forward otherwise it throws. That makes it easier to "diff" at the single prop level too so I am not convinced that's needed or desired but my point is that we could (should?) start simple and throw somehow when things are ambiguous so we can refine later on? anyway, I am not opposed, just sharing why I think sparse attributes changes are not that cool as a feature, imho
• glad to hear there is work ... having native and well done hydration, even if some JS orchestration will be still needed, would be a huge win for the Web

[keithamus]

I'm of the opinion that we should do nothing special with attribute names, so e.g. @foo=1 should call setAttribute('@foo', '1') and not introduce special semantics. I think libraries can do an attribute walk after parse and sweep any of these up. In light of that change, does it significantly reduce or increase value for frameworks?

Perhaps we can introduce a mechanism for a lifecycle hook so that before an attribute is set, some JS machinery can kick in.

[keithamus]

The sigil syntax isn't shared (or even agreed upon) among frameworks which makes this a challenge though. For example Phoenix uses :if=/:for=, while Angular has *ngIf=. While Lit uses @click=, Qwik uses onClick$=.

My concern is that these sigils are not intrinsically part of the platform - they lack precedent. Frameworks haven't converged so we have no framework precedent. The result will be years of litigation about which ones are the right set, if any.

OTOH if we say "attributes don't do anything special, but we'll give developers the primitives to iterate over expressions" that should be far more tractable (therefore shippable).

Let's say, for example, if we had a template like:

const view = (state) => DOMTemplate.html`
  <input
  value=${state.name} oninput=${state.onInput} bool:required=${state.required}
    prop:value=${state.name} unfurl:class=${{ active: state.active }}
  >
`;

Each of the interactive attributes could have their setAttribute calls deferred and lazily evaluated until the first .setValue or so. This would mean frameworks could easily intercept parts and provide their own semantics on top:

function applyFrameworkSemantics(instance, values) {
 for (let i = 0; i < instance.parts.length; i++) {
  const part = instance.parts[i];
  if (!(part instanceof SingleAttributePart)) {
   continue;
  }
  const value = values[i];
  const { element, name } = part;
  if (name.startsWith("on")) {
   const type = name.slice(2).toLowerCase();
   setEventListener(element, type, value);
   continue;
  } else if (name.startsWith("prop:")) {
   element[name.slice("prop:".length)] = value;
   continue;
  } else if (name.startsWith("bool:")) {
   element.toggleAttribute(name.slice("bool:".length), Boolean(value));
   continue;
  } else if (name === "unfurl:class") {
   for (className in value) {
    element.classList.toggle(className, value[className]);
   }
   continue;
  }
  // Fallback to string values
  part.setValue(value);
 }
}

SingleAttributePart would still be a simple implementation:

class SingleAttributePart extends TemplatePart {
  readonly element;
  readonly name;

  setValue(value) {
    if (value === DOMTemplate.nothing) {
      this.element.removeAttribute(this.name);
    } else {
      this.element.setAttribute(this.name, String(value));
    }
  }
}

Hopefully from there it would be easy to imagine all the ways in which this grants frameworks the flexibility to provide their own semantics and I don't think it would be too costly as they're likely going to iterate across all parts at least once, no?

[WebReflection]

I think that works to me

[justinfagnani]

My concern is that these sigils are not intrinsically part of the platform - they lack precedent.

This is fine for new features. CSS and JS have to settle on syntax for new features quite often.

And these modifiers do have semantic precedent in template languages: most HTML-focused template languages let you bind to events and properties. And the syntaxes don't even diverge very much. They look like attributes, they just have different prefixes or sigils.

Choosing a base syntax is ok - the platform can make a choice here. The alternative is that this is an API only for frameworks that add their syntax on top. I think it would be an anti-developer move to say that developers must use a library or their glue code to get the most minimally useful API. It would be like Temporal not actually working for date parsing out of the box, and requiring you to bring your own code or use a parsing library.

I believe we can get to a good baseline syntax that's meets developer expectations for expressiveness while allowing other template systems to use their own syntax. And I don't think we should avoid a syntax out of hypothetical objections.

I also think that we can rationally arrive at an acceptable base syntax. I talk about the various syntaxes in use here. We could add more to that comparison which I would bet would only strengthen the pattern. Template systems break down into two categories: those that do not differentiate between properties, events, and attributes; and those that do.

I think we must rule out not differentiating between them because properties, events, and attributes are three distinct API surfaces and are not compatible. Once you filter for those that do make the distinction, the only question left is minor syntax differences. .foo vs :foo, vs [foo], etc.

[lukewarlow]

I agree that we shouldn't just be treating everything as a setAttribute(), frameworks don't necessarily agree on what to do or what syntax to use but they all seem to agree on what not to do, and it's that.

The problem with something like prop: as a prefix is that is actually a namespace, the oninput style of attribute is an event handler content attribute. It feels wrong to build in a special namespace prefix that's not actually a namespace. It also feels wrong to use the on prefix as a "this is an event handler". Why do we prevent authors from setting event handler content attributes (yes they're bad but that's what CSP is for)?

I'm aware of both Vue and Lit using @ as the event handler prefix.

Interestingly, Vue has a way to add event handler modifiers as part of its syntax. So it can be like @scroll.passive= idk if that's useful but thought I'd mention an alternative to how Lit and uhtml do. See https://vuejs.org/guide/essentials/event-handling.html#event-modifiers.

I've re-read and realised what Keith was saying and it's more acceptable, but I still think it would be better for the platform to choose a higher level syntax for this.

[WebReflection]

Why do we prevent authors from setting event handler content attributes (yes they're bad but that's what CSP is for)?

there's a difference between onclick and @click in mostly every framework (or on:click or others) ... one uses DOM Level 1 listeners, no option to pass options to that event, easy to overwrite out of the blue and break previous logic, one uses addEventListener DOM Level 3 which should be the preferred way for everything + it wouldn't require CSP, Web safe by default.

That being said, onclick="console.log(event.type)" is not up for debate, that would work anyway, onclick=${listener} might be though, that's up to the library/utility owner's decision to do whatever feels more convenient.

edit

@scroll.passive= does not offer ergonomics or expectations because the passed value might be more complex as otpions for the listener + it requires arguments parsing order to know something was opting in for options around that event so that @scroll=${handler} @scroll.passive=${true} and @scroll.passive=${true} @scroll=${handler} might have different results, which is ugly, imho.

[janechu]

I'll jump in here and mention FAST's current progress in this area and what our thinking is. We recently started work on implementing a solution which is available as a prerelease in 3.0.0-rc.1 you can see our markup https://fast.design/docs/3.x/declarative-templates/defining-elements/ which is a bit handlebars-like. There are similarities with @justinfagnani proposal, though we separated out bindings the server cares about for rendering Declarative Shadow DOM, and bindings only the client cares about. In this way we can make life easier for server side authors who would be writing their own parsers.

On the client our solution was to use a custom element (f-template) that contains the template which is then interpreted and attached to the defined custom element with the given tag name.

I agree with @justinfagnani I do prefer we build for what developers want out of the box. Ideally any JavaScript is purely component logic, not supplied by frameworks. Less JavaScript shipped, better performance, better developer experience.