RFC - Rethinking the mapping of template props to DOM element attributes/props

[trusktr]

(sparked by thoughts in ryansolid/dom-expressions#351)

Hmmm, HTML is case insensitive, so in HTML fooBar="", FOOBAR="", and fOoBaR="" set the same attribute:

document.body.setAttribute('FoObAr', '123')
console.log(document.body.attributes.foobar.value) // 123
document.body.setAttribute('FOOBAR', '456')
console.log(document.body.attributes.foobar.value) // 456

But ...

Rethinking template DOM attributes/props mapping?

... because Solid reads the template before mapping it to DOM, it knows ahead of time what the user wrote.

I've been thinking, maybe it may be good to change the rules to be more consistent with the wider ecosystem (outside of Solid), simplify the template implementation a little bit, and give users 100% control of elements without any compromises (regardless if the elements are custom or builtin).

How?

The following is based on Lit's html, Pota's JSX and html, and chats with @titoBouzout (author of Pota):

• because we see the template ahead of time, we know if the user wrote foobar vs FOOBAR.
• it is possible that for sake of consistency, we could have foobar="" always set an attribute regardless of the type of element the attribute is on (custom or builtin)
  • right now foo="" sets the foo attribute on builtin elements by default, otherwise it sets the foo JS property on custom elements (web components).
    • This may not be obvious to new users at first, for example it is not mentioned in the new docs here or here.
  • foobar="" and fOoBaR="" would always set the same attribute (on custom and builtin elements)
    • attr:foobar="" and attr:fOoBaR="" would have the same behavior of always setting the same attribute
• case sensitivity would be distinguished only with property syntax where prop:foobar="" would set a .foobar JS property, and prop:fOoBaR="" would set a .fOoBaR JS property
  • html would have Lit-compatible syntax besides prop: syntax: .foobar="" would set the .foobar JS property, and .fooBAR="" would set the .fooBAR JS property.
  • prop:foo (in JSX ot html) and .foo (in html only) would always be needed to set a JS property regardless if custom or builtin element
• Boolean attribute syntax would be case insensitive, f.e. bool:foobar= and bool:FOObar= would handle the same attribute (but with boolean treatment where truthy means the attribute should exist, and falsy means the attribute should be removed) regardless if custom or builtin element
  • html would have Lit-compatible syntax besides bool: syntax: ?foobar= and ?fooBAR= handle the same attribute
  • when its a static attribute (boo:foo="" instead of bool:foo=${}), it would work like setting a string value without boolean syntax: bool:foobar=".." would be equivalent to foobar="..", setting the attribute (case insensitive) to a string to emulate that in HTML foobar="" and foobar="false" are both "truthy" in most HTML cases
  • Note, there are another type of attribute called "enumerated attributes" that accept certain values. Sometimes an enumerated attribute may accept values of "true" and "false" making it an alternative type of "boolean attribute", where they set JS properties to false when the string value is "false" otherwise they set the JS prop to true, and when the attribute is omitted they set the JS property to true or false depending on its default.
    • Lume, for example, does boolean handling in that way, where the HTML attributes foo, foo="", foo="true", and foo="anything" all set the JS property to true; foo="false" sets the JS prop to false; and omitting the attribute sets the JS prop to true or false based on the JS property's default value (in the case of Lume that's the class field initial value).

Why?

This would have some benefits:

• simpler template implementation: it would no longer have any huristic that tries to guess whether an attribute or a JS property should be set, no special case attribute-to-property name mappings or behavior (except for very special global cases like style perhaps), etc.
• simpler for users to understand (or to make assumptions about) out of the box without the documentation having to mention anything about a huristic for handling between custom and builtin elements or mapping the values to attributes vs JS properties
• consistency as in other frameworks do this (or some of this), for example Lit does exactly this while React 19 doesn't offer full control (React 19 will still have issues, for, example, and despite the warning signs starting here that are honestly quite easy to avoid), but React 19 will map case-sensitive JSX prop names to JS properties when they exist, otherwise will fall back to attributes. For React 19, you will need to understand this monster table to know how it works, and we will still have to break out of the template with refs to achieve things in various cases.
• consistency as in what you see is what you get: you know from reading the template _exactly_ what it is doing. Compare the following rules to the previous bullet point's monster table (_ represents a custom element or builtin element, it would not make a difference):
  • <_ foo=... /> -> always set the foo attribute
  • <_ prop:foo=... /> -> always set the foo JS property
  • <_ bool:foo=... /> -> always add the foo attribute if the interpolated value is truthy, otherwise remove the attribute. If non-interpolated, apply the string value to the attribute as if bool: was not used (attribute always exists in that case).
  • <_ fooBar=... /> -> always set the foobar attribute
  • <_ prop:fooBar=... /> -> always set the fooBar JS property
  • <_ bool:fooBar=... /> -> always add the foobar attribute if the interpolated value is truthy, otherwise remove the attribute. If non-interpolated, apply the string value to the attribute as if bool: was not used (attribute always exists in that case).
  • <_ foo-Bar=... /> -> always set the foo-bar attribute
  • <_ prop:foo-Bar=... /> -> always set the "foo-Bar" JS property
  • <_ bool:fooBar=... /> -> always add the foo-bar attribute if the interpolated value is truthy, otherwise remove the attribute. If non-interpolated, apply the string value to the attribute as if bool: was not used (attribute always exists in that case).
• There would no longer be a need for attr:, but it could stay for back compat.
• The above, plus .foo and ?foo syntax for html tagged templates as alternatives to prop:foo and bool:foo respectively.
  • Lit syntax will make us compatible for type checking and intellisense of html tagged templates with tools like lit-plugin, @Matsuuu's custom-elements-language-server, and more, for IDE type checking and intellisense, and eslint-plugin-lit for linting.
• Lit's @foo syntax for events in html tagged templates, allowing onfoo="" to set an onfoo attribute, .onfoo to set a JS property, and @foo to specifically listen for foo events.
  • In Solid we have on:, but without the colon Solid will currently listen to an event instead of setting an attribute.
  • attr:onfoo and prop:onfoo allow full control to be possible, where plain onfoo might still always handle events if back compat is important, or if its just moreconvenient because all the native HTML events already work that way.
    • need to double check Lit's behavior on this particular case, but I think for sake of consistency setting an attribute might be the way to do it, with @ for being explicit about events.
  • if we have @, then we at least have a doorway to type checking and intellisense fully compatible with what the Lit community has already been building. This is as similar as adopting TypeScript from React JSX, but now also TypeScript from Lit, and opening doors to possibly compiling html templates ahead of time, not only JSX.
• The Lit-inspired rules are fundamentally easier to wrap our head around than what React 19 will have. In React 19, behavior will arbitrarily change depending on whether or not a custom element has a JS property. An example of one of many problems:
  • User is relying on the CSS style [foo] { color: cornflowerblue }
    • If the element does not have the foo JS property, the style will work.
    • If the element has the foo JS property, the style won't work!
    • User will need to avoid the JSX template and instead use a ref, el.current.setAttribute('foo', '')

The idea is full control for the user.

The approach I've outlined, and which Lit takes, is, simply put, the simplest way to do it, with the least possible confusion, with no compromises and full control of Builtin Elements or Custom Elements.

Oh, hah. And this approach would also have a small side effect of increasing performance by eliminating conditional checks like isCE. The gain is negligible, but still.

I cannot think of any downside regarding the developer experience: full control, simplified implementation and mental model.

Breaking change

This would be breaking of course, so maybe it would need to be shipped with Solid 2.0?

Or, to release something like this in 1.x, there could be a babel-preset-solid option to enable the new mode (documenting that if the option is enabled then it will be compiling any 3rd party JSX code with new semantics and thus 3rd party code may break) as well as a new solid-js/html2 export that has the new html behavior (rename it to solid-js/html in 2.0). Or similar.

This also requires updating SSR to work with the new setup, and will require considering how to serialize data so that the HTML payload will properly encode how serialized values get set onto elements (string attribute case insensitive, bool attribute case insensitive, or JS property case sensitive).

Examples

I made a Lit playground example showing the various cases:

Lit playground example

In particular, note the behavior of static attributes (f.e. .foo="123"). As noted there, that's because those are verbatim actually-valid HTML attributes, and Lit's html template sticks close to HTML standard.

However! I would imagine that sometimes people get confused when .foo="bar" does not set the JS property to "bar".

Solid's could deviate from this a little bit so that ?foo and .foo always have boolean and JS prop behavior regardless if they are static or interpolated (but this might mean breaking differences with the type checking and intellisense support from Lit's community (maybe not breaking, but maybe static/literal attributes won't be matched with JS props for type checking/intellisense like interpolated attributes will be)).

There could possibly still be attr: for when someone actually intends to set an attribute prefixed with a character, which would be the rare case, f.e. attr:.foo="123" and attr:@notEvent="123", although maybe not worth supporting that. Maybe being that close to native HTML like Lit is not as ideal, and this small deviation would eliminate any confusion so that .foo always means set the property, ?foo always means boolean treatment, and @foo always means hook into the event.

Pota's html gets a lot closer to the above spec. Here's a Pota example.

Pota playground example 1

In the Pota example, we can see that it always treats .foo= and ?foo= as for JS properties and boolean attributes, regardless if the expression is static or not, which is less confusing.

el.setAttribute('.foo', '...') and el.setAttribute('?foo', '...') both throw runtime errors, so it is very unlikely people use these attributes which can only be set as readonly during parse time, for example,

document.body.innerHTML = '<p .foo="123"></p>'
console.log(document.body.children[0].getAttribute('.foo'))

logs "123" but the .foo attribute cannot not be set later with setAttribute.

Pota's behavior is different from the above spec in one in that dash-cased .foo-bar= attributes will currently set camelCased .fooBar JS properties. To match with the idea above, .foo-bar= would instead set the ["foo-bar"] JS property, and someone would instead use .fooBar= to set the same-name .fooBar JS property. This modification would be ideal because currently (in both Solid and Pota) if someone actually wants to set a foo-bar JS property, they can't. The change is easy, removes a string manipulation, and what we see is what we get which is easy to understand.

Lastly, noting that Pota is more closely aligned with the above spec and does not treat .foo="123" differently from .foo="${'123'}" (they both set the .foo JS property, whereas Lit sets an attribute and a JS property respectively), this Pota example,

Pota Playground example 2

shows that having two occurrences of .foo-Bar= causes an issue (see the note about the "word" value) because they are both treated the same (set the JS property) hence there's a name collision. In Pota we'd probably want to either accept the last same-name attribute (akin to defining the same property in a JavaScript object and the last one wins), throw an error, or at least show a warning, but overall if we remove the duplicate (f.e. rename it to .foo-Bar2) we get the behavior of the above spec apart from the dash-case difference.

Another difference between Pota and the spec and Lit is that Pota requires quotes around all value interpolations. For example in Pota .foo=${123} will not work while .foo="${123}" will work. I'm not sure how complicated this is to fix (Pota's implementation focuses on simplicity), but from a usage perspective, .foo=${} is more ideal because less characters and symbolically the string value is replaced with an interpolation.

Pota's templating is the closest reference implementation of the above spec so far. Note, I didn't show usage of prop: or bool: which should behave the same as . and ?.

[trusktr]

The more I think about this, the more I dislike React 19's new direction: React users are going to face issues with assignment working differently depending on which elements they stick into their templates, leading to confusion.

It is not a very good approach considering that the Lit-based/Pota-based alternative described above is, to be honest, easiest and simplest on all sides with no magic and no chance to fail.

[trusktr]

As an example of the migration that would be needed for users with this new attribute/property handling, with Lume we currently write templates like the following to send values to JS properties which is faster than string attributes:

return html`
  <lume-box
    position=${[1, 2, 3]}
    align-point=${[1, 2, 3]}
    mount-point=${[1, 2, 3]}
  ></lume-box>
`

If the new above spec is implemented, then to achieve the same result the template would need to be converted to this:

return html`
  <lume-box
    .position=${[1, 2, 3]}
    .alignPoint=${[1, 2, 3]}
    .mountPoint=${[1, 2, 3]}
  ></lume-box>
`

Note that with Lume specifically, due to how it sets up its attributes, the original dash-case template would still work, because it would then be setting the attributes (instead of JS properties) with the string values "1, 2, 3" from the stringified arrays, and then the string values would be deserialized back into number arrays. So although it would still work, there's be an array -> string -> array conversion happening.

[titoBouzout]

That won't work, html attributes are case insensitive, see this example

Document.parseHTMLUnsafe(`
<div .someFoo="bar"/>
`).body.innerHTML

It transforms .someFoo to .somefoo so we lose data, that's why pota transforms dash separated names in properties to the camelCase form. Because its the only way to keep the case.

[trusktr]

True that it won't work with an approach like Pota's use of the native DOM parser. Question is whether or not it is worth making a custom parser so it is case sensitive like Lit's html.

[titoBouzout]

Heuristics

I do not like that this proposal removes the heuristics. It seems to default to attributes always unless you use .propName(html) or prop:propName(jsx). The heuristic is the happy path, and you have full control of the exception using the explicit namespaces.

For example,

1. having to use <input props:value="hola"/> instead of <input value="hola"/>
2. some people would prefer to use <div ariaRole="menu"/> instead of <div aria-role="menu"/>
3. setting a property could be faster than setting an attribute [citation needed]

The heuristics (this is incomplete)

1. A heuristic that maybe works nicely is to check prop in element, if that's true then we add it as a prop, else it gets added as an attribute.
2. svg, seems like svg needs all names to be attributes

[titoBouzout]

lit style syntax

Im not sure if I like lit-style-syntax, I would prefer to use prop:, attr:, bool:, on: on the html function

1. is a bit alien to prop: attr: bool:, on: conventions, it will be consistent with JSX using the same thing.
2. There's no way to force something as an attribute. It has .propname for locking to properties but no syntax for locking to attributes. This is specially relevant if the default is a heuristic

[titoBouzout]

Pota Thread

Another difference between Pota and the spec and Lit is that Pota requires quotes around all value interpolations. For example in Pota .foo=${123} will not work while .foo="${123}" will work. I'm not sure how complicated this is to fix (Pota's implementation focuses on simplicity), but from a usage perspective, .foo=${} is more ideal because less characters and symbolically the string value is replaced with an interpolation.

It's because pota joins the template with <pota></pota>, and without quotes that will mess up the browser parsing

Document.parseHTMLUnsafe(`
<div one=<pota></pota> two=<pota></pota> />
`).body.innerHTML

I will have to think if I can handle this, but I sort of doubt it without some regexp and loops gymnastics which I want to avoid.

Currently, it works like this

<div one="${one}" two="${two}">${three}</div>

to

<div one="<pota></pota>" two="<pota></pota>"><pota></pota></div>

then replaces "<pota></pota>" for "pota"

<div one="pota" two="pota"><pota></pota></div>

Then, it knows if an attribute is an interpolated value because its value is "pota", and it knows if a tag is an interpolated value because the tagName is "pota"

[titoBouzout]

Also about

shows that having two occurrences of .foo-Bar= causes an issue (see the note about the "word" value) because they are both treated the same (set the JS property) hence there's a name collision. In Pota we'd probably want to either accept the last same-name attribute (akin to defining the same property in a JavaScript object and the last one wins), throw an error, or at least show a warning, but overall if we remove the duplicate

Duplicate names in attributes get removed tby the browser parser, see

Document.parseHTMLUnsafe(`
<div one="1" one="2"/>
`).body.innerHTML

will yield

<div one="1">\n</div>

Don't think I can do anything about that, and trying to handle this will just make it slower.

A curiosity is that the browser keeps the first value, contrary to your suggestion of keeping the last value.

[titoBouzout]

Boolean Attribute

About the ?boolname

should ?foo="" (with an empty static string) be false? Or true like foo=""?

I think it should just be removed to make it simpler to think about it. The whole idea is falsy/truthy, and "" (empty string) is falsy.

should ?foo="something" write the attribute value?

No, don't think it's a good idea, it's confusing. Having more behaviours attached for things that can be done by other means increases complexity and code size.

[titoBouzout]

Reference Table

We have been working on this Google doc to have a reference table, its mostly complete, but we may be missing something.

https://docs.google.com/document/d/13jc0vu2w2hSACeTx6QHc5fz3giFF9sXDzPZ2VjALW-A/edit?usp=sharing

[ryansolid]

I want to put it out there even if we removed heuristics for web components the base heuristics for booleans/value etc would stay. We have reasons to treat known attributes with special characteristics, so I imagine any proposal would only apply to general attributes applied to elements.

1. having to use <input props:value="hola"/> instead of <input value="hola"/>
2. some people would prefer to use <div ariaRole="menu"/> instead of <div aria-role="menu"/>
3. setting a property could be faster than setting an attribute [citation needed]

So what I'm saying is you'd never need to do 1 because value is special.. Especially on an input element.

2 is interesting from an SSR standpoint.
3 Often this is the case but also for the general case I don't know it matters that much.

[trusktr]

don't know it matters that much.

It matters for animation. We don't want nonstring-to-string-to-nonstring serialization/deserialization for animated values.

For one-off things like toggling a menu open or closed, it doesn't matter.