Content vs IDL attributes and "browser quality" elements

[hunterloftis]

Browser elements like <input> separate content attributes from IDL attributes - especially for enums - in a way that isn't common in Lit elements:

Most of the time, IDL attributes will return their values as they are really used. For example, the default type for elements is "text", so if you set input.type="foobar", the element will be of type text (in the appearance and the behavior) but the "type" content attribute's value will be "foobar". However, the type IDL attribute will return the string "text".

A visual example may be helpful:

The HTML spec goes into more detail on how browsers reflect enumerated attributes:

• https://html.spec.whatwg.org/multipage/common-dom-interfaces.html#reflecting-content-attributes-in-idl-attributes
• https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#keywords-and-enumerated-attributes

While developing a textual input component in Lit that aspires to be "native browser quality," I've reproduced the behavior of <input> by separating content attributes (DOM) from IDL attributes (state):

const textfieldTypes = ['text', 'url', 'tel', 'email', 'password'] as const;
export type TextfieldType = typeof textfieldTypes[number];

// ...

@property({ attribute: 'type', reflect: true })
private _type: TextfieldType = 'text';

@state() // actually @internalProperty()
get type(): TextfieldType {
    return textfieldTypes.find((t) => t === this._type) ?? 'text';
}

set type(val: TextfieldType) {
    const prev = this._type;
    this._type = val;
    this.requestUpdate('type', prev);
}

In Lit, this pattern is more verbose than the typical reflect: true and it took me a few tries to land on this solution while referencing the docs. Which begs the questions:

• Are there reasons to avoid imitating browser element behavior like this?
• Is there a more Lit-idiomatic way to implement this functionality?

[Westbrook]

Would it make sense to have a decorator that did this for us? Could a decorator do this?

[bathos]

It is possible: we do this with a custom decorator currently. There's a bit more to it depending on how closely you want to match the native behavior, but iirc requestUpdate is sufficient to hook into lit's batched update behavior. The more faithful it is, the more overhead it has, though, so it's not unreasonable for lit to depart a bit from the HTML pattern imo ... but I do wish lit didn't use "reflect" to mean the exact opposite of what it means in HTML/Web IDL (a content attribute is reflected as a Web IDL attribute, not the other way around, and while it seems like you could look at it either way, the difference ends up observable in lit in various ways).

[justinfagnani]

We can't decorate the attribute directly, only the property, and reflection theoretically should be symmetrical, so it seems ok to put it on the property. I don't think it quite means the opposite the way we use it - the attribute still reflects to the property.

[bathos]

@justinfagnani yep, apologies if it was unclear but I was not suggesting lit's approach is wrong, only that I think the choice of terminology is unfortunate. if someone is trying to implement HTML-style content attribute reflection like the OP, they will quickly learn that lit's reflect means something very different. It's prob a ship sailed too long ago to push for a rename tho I realize.

[hunterloftis]

@bathos I'd be interested in seeing your custom decorator, if it's public!

[bathos]

It's not in an open source package currently, but the code is visible online; will send you a link elsewhere.

[justinfagnani]

Interesting topic.

Are there reasons to avoid imitating browser element behavior like this?

I'd probably ask if there are good reasons to emulate it. There are some nice things about making sure properties are valid, but setting a property and reading it back immediately with a different value breaks expectations around how JS objects and properties behave. My general rule of thumb for accessors is that they should try to work like plain properties as much as possible. So the question because do you want to behave like HTML elements or JS object? And what do you get out of acting like built-in elements, more than a purity aspect?

Is there a more Lit-idiomatic way to implement this functionality?

I was thinking an attribute converter could help here, but it seems like that would only help for values set as attributes. Converters don't really have the shape to validate and transform property sets (though you could maybe force it into toAttribute).

I think we would consider a feature request for this, because the type of solution you showed actually creates another property for internal storage and another set of accessors, and the usage of @property() and @state() are backwards (@state() is supposed to be private, @property() public). Maybe there could be a way to an attribute converter to validate the property value before it's stored, or maybe another hook.

[hunterloftis]

I'd probably ask if there are good reasons to emulate it ... what do you get out of acting like built-in elements, more than a purity aspect?

There is certainly a purity aspect to it, but there are some additional reasons you might want to act like a built-in element. If you'd like to provide a drop-in replacement for a built-in element, it's important that all the nuanced behaviors match.

Another motivator is safety: if your element guarantees that it can only represent valid internal states, then a single error in some JS somewhere on the page (someInput.type = "explode") doesn't cause your component to malfunction internally, or to reflect an impossible or undefined state. Here's an example of an <img> protecting its state:

Of course, you can accomplish part of that with idiomatic Lit, but the validated state won't be reflected:

@property({ reflect: true })
public type: TextfieldType = 'text';

protected get validType(): TextfieldType {
    return textfieldTypes.find((t) => t === this.type) ?? 'text';
}

protected render() {
  // <input type=${this.validType} .../>
}

I think we would consider a feature request for this ... Maybe there could be a way to an attribute converter to validate the property value before it's stored, or maybe another hook.

Thanks for considering our use-case! Should I create a feature request issue from this discussion?