The CSS selector desugaring needs better documented.

[dead-claudia]

In the documentation, it briefly goes over the CSS selector sugar. However, it doesn't document precisely how it gets desugared:

• m("tag[attr]") → m("tag", {attr: true})
• m("tag[attr=]") → m("tag", {attr: ""})
• m("tag[attr=...]") → m("tag", {attr: "..."})
• m("tag[attr='...']") → m("tag", {attr: "..."})
• m('tag[attr="..."]') → m("tag", {attr: "..."})
• m("tag.foo.bar", {class: "baz"}) → m("tag", {class: "foo bar baz"})
• m("tag[class=foo]", {class: "bar"}) → m("tag", {class: "foo bar"})
• m("tag.foo[class=bar].baz") → m("tag", {class: "foo bar baz"})

Also, our magic true → "" semantics for attributes (but not properties!) needs documented.

[dead-claudia]

For context, this recently came up on Gitter, but I've seen it come up several times previously, and I myself occasionally run into this glitch. It should probably be made clear that tag[attr] is different from tag[attr=''] in Mithril's selector, and that it's only equivalent for attributes.

In addition to all this, a nice and clear warning should be left in the hyperscript docs that explains that:

1. Most DOM attributes have similarly-named properties
2. For several properties sharing names with DOM attributes, such as input.required and progress.position, their values aren't strings, and so you could unwittingly encounter weird coercion issues if you try to assign strings to them. (For example, m("input", {required: ""}) will set input.required = "" on the backing DOM element, and since Boolean("") === false, this is counterintuitively equivalent to input.required = false.)
   • This also carries for the readonly (attribute)/readOnly (property) example specified in the docs.
3. And of course, this: https://github.com/MithrilJS/mithril.js/issues/2345

---

Side note: this section is redundant with text within the DOM attributes section and needs removed. And the DOM attributes section needs renamed to something like DOM attributes and properties (and Style attribute to Style property) for clarity.

[dead-claudia]

A PR resolving this should probably combine this with MithrilJS/mithril.js#2345 and kill both in one fell swoop. They're closely related enough, especially in light of the gotcha in the previous comment, that it'd be worth combining them and approaching it holistically.

[dead-claudia]

This is mostly fixed, but the m("tag[attr]") vs m("tag", {attr: true}) is left too implicit to be clear.

[anonghuser]

I guess m("tag[spellcheck=false]") becoming <tag spellcheck="true"> is also related to the property being set to the truthy string "false". You need to embrace this quirk and use m("tag[spellcheck='']"). Should it simply be documented, or the implementation actually changed?

[pygy]

m("tag[spellcheck=false]") should produce <tag spellcheck="false">.

This is a bug.