...attributes -- Component API and Discoverability

[NullVoxPopuli]

A couple co-workers brought up some interesting points this morning.

Given that
...attributes can be placed anywhere in a component

You

• don't know if ...attributes is used at all (everyone should be using ...attributes though -- the calling context is in charge of layout, and you may want to pass layout classes or aria attributes to your sub-component )
• don't know what element ...attributes will be placed on.
  • is it the outer-most element? (imo, it should be)
  • is it some other element? (this, to me, means that the abstractions need to be re-worked so that ...attributes can be the outer-most element
• don't know that args are or aren't overwriting the attributes
  • for example:

    <div ...attributes aria-label={{@ariaLabel}}>

Questions for the community:

• should we add a lint rule to suggest that ...attributes should only be used in the top-most element?
• should we have some additional tooling ((u)ELS?) to tell us if ...attributes is used, if any @args overwrite / merge any of the attributes.

The main thing we're after here is clarity without having to know implicit community convention -- because implicit community convention can't be programmatically enforced atm.

Related: ember-learn/guides-source#1286
(the specific component in that link, Input, isn't important to this issue, but the problem is there)

[chriskrycho]

My take here is: this should become standard part of API documentation for add-ons, internal and external. But, and this is key: what happens to the ...attributes should not always be documented. In many cases, it's effectively internal implementation details, same as "what exactly do you do with @bar once I hand it to you?"

• should we add a lint rule to suggest that ...attributes should only be used in the top-most element?
• should we have some additional tooling ((u)ELS?) to tell us if ...attributes is used, if any @args overwrite / merge any of the attributes.

Almost certainly not, at least as a default. These are, again, internal details. You might have very good reasons for choosing always to stomp certain things the user might pass in. E.g. in maintaining accessibility, if the user passes in values that would break your internal invariants about how certain elements are related, you want to be able to guarantee that your invariants win.

[MichalBryxi]

Disclaimer: I'm the mentioned coworker from the first comment.

I feel that the hiding of "implementation details" might be problematic. Let's say I found an addon that has component <Foo /> that has arguments @bar and @baz. And <Foo /> contains more than one HTML tag. Now I want to add some HTML attribute to achieve X, because X is not supported by the arguments provided. Maybe:

• generic aria-* for better a11y
• or new-ish loading="lazy" for better performance
• or a ping="[URL]" for tracking purposes

Whichever attribute from my list I chose to implement, it will depend on which HTML element it is being applied to (not all of them are applicable after all). And how are they applied (why is my value not here? oh it's being overriden :sad-panda:).

And at that point I as a consumer have to go and look at the source code, because it is not obvious from the syntax and it is (usually) not in the docs.

I'd say that if we force the consumer of the addon/component to look at the source code of the addon because the syntax OR the docs are not being explicit enough, we're doing the documentation wrong.

[ro0gr]

These are, again, internal details.

I believe it should not be like that. Allowing an "addon" author to place ...attributes wherever they want feels like a footgun to me. In its current form It may easily lead to breakages of HTML validity or introduce styling regressions. There are few examples:

---

Let's assume we render smth like:

<SomeonesSuperComponent id="myId" />

I'm pretty sure it should result to a single element being rendered with an ID passed to it.

However, If the author of "SomeonesSuperComponent"'s decides to apply ...attributes multiple times in their template, it would break HTML, cause we can't have the same ID on the same page.

It would break HTML, cause we can't have the same ID on the same page.

---

Similar happens when you just want to give some outer styling to your component:

<style>
  .my-component {
    margin: 10px;
  }
</style>

<div>
  <SomeonesSuperComponent class="my-component" />
</div>

with that ^, I, as a developer, expect to have my SomeonesSuperComponent's outer element to have 10px of margin within a parent div. However, a SomeonesSuperComponent's author may decide to apply ...attributes somewhere deeper than top-most element, which would break my expectations and design :(

---

The last but not least. From time to time, I encounter that some of my tagless component templates are missing ...attributes. As a result, when I render <SomeonesSuperComponent it just doesn't accept any attributes, which is highly unexpected to me.

---

TLDR; I believe there should not be a way to apply ...attributes somewhere else then a top-most element of a tagless component. Only once per template.

[pzuraq]

@ro0gr FWIW, we spent a long time discussing that as a possibility in the community during the lead up to adding angle bracket syntax and the ...attributes keyword. I think reading back in some of the older RFCs might be a good way to get some context on those older discussions, and the reasons why it was decided to not place these restrictions on the usage of ...attributes.

That said, if it turns out that there are antipatterns like you're describing, I think that's a perfect place for linting rules 😄 Still allow the flexibility, but try to have a general rule of thumb for best practices.

[ro0gr]

@pzuraq yes, i observed that discusisions, and I think, I just haven't realized all the implications good enough. I'm not complaining, just sharing my findings.

I agree, we can try to reduce misuse(in my opinion) of attributes via linting, but I'm unsure if it can distinct between tagless VS tagName components...

I think, Ideally, i'd be happy, if I could skip writting it at all, and have default behavior applied implicitly in case of a single root(95% of my cases?), until explicitly specified "...attributes". Not sure if it's feasible though, and which layer's resonsibility should it be.

[pzuraq]

That was one of the options that was discussed. I believe the reason we didn't choose it was because, as time has gone on, we've preferred more explicit APIs. Implicit APIs like that often come back to bite you.

For instance, imagine if a junior Ember dev saw a template for a component like this:

<section>
  <!-- ... -->
</section>

And was tasked with adding a new header above the section. They go ahead and add it, without realizing that there is implicit behavior being caused by the current layout, and then things suddenly break 🙃

With explicit syntax and rules, you avoid breakage (because it's explicit, and allowed), and you give a hint to developers that something is special about this particular element.

[ro0gr]

I feel, if someone pass attributes to the component with multiple root elements under irs template, rendering should fail. Otherwise, the user of such component can not rely on patterns used in regular HTML/CSS

[ro0gr]

It can also prevent a junior to make a wrong thing

[pzuraq]

@ro0gr that would be one way to solve these problems, and we did discuss those solutions at the time. I think making those changes at this point would be very significant breaking changes, so it's unlikely that it will happen.

Happy to talk through why the decisions were made, and what the perceived pros and cons were, but personally I think it'd be best to keep the discussion here focused on figuring out best practices with the existing behavior.

[ro0gr]

keep the discussion here focused on figuring out best practices with the existing behavior.

@pzuraq Unfortunatelly, I don't think there can be good practices to apply ...attributes on something different than outer-most element.

If there is no single outer element, I'd not recommend to use ...attributes at all. Otherwise, this component just becomes unreliable to style. The same is valid for cases when ...attributes applied somewhere deep in the component markup. Also, at some point you may realize, you are missing an outer element attributes, and duplicate ...attributes, and that's where things start going totally unmanaged. I'd be happy to see an example when ...attributes are really useful outside of outer-most element, and don't cause more problems than benefits.

Though, I believe cases like that are pretty rare in real apps. They are so special that it seems more reasonable to just use arguments explicitly.

That being said, I believe, we should discourage community from patterns like that, and template lint can be a great tool for that! And, maybe, at some mid/long-term point, we can even disallow such a freedom for ...attributes completely.

[Gaurav0]

One exception tends to be input / textarea elements with surrounding and/or sibling labels and error messages. In that case, ...attributes makes more sense on the input.

[ro0gr]

@Gaurav0 Thanks for example!

I agree, this seems to be the most prominent use case, when you want to use ...attributes in the nested element. As already mentioned, exposing the ...attributes is an internal implementation details. However, in case if expose it from nested element, like <input wrapped by something, that would be details not of the custom input component, but details of the HTMLInput. That can go wrong in many ways:

• overtime a feature-set of your custom input would grow. You may need to know count of typed letters, change styles for the whole component based on its readonly state... At the current moment requirements like that would require you to migrate out of natve value, readonly to args @value, @readonly. That would make your component API inconsistent. Something would keep being attributes(until next requirement), and something would become an arg.
• At some point you may also want to replace <input with [contenteditable] element for some reason, in this case your component's API breaks.

But that's not the only problem. Let's assume the following minimal example of such custom input implementation and usage:

{{#let "InputWithAttributes" as |scope|}}
  <div class={{scope}} ...attributes>

    {{#if @label}}
      <label for={{this.inputId}}>{{@label}}</label>
    {{/if}}

    <input
      ...attributes
      id={{this.inputId}}
      class="{{scope}}-input"
    >

    {{!-- error here --}}
  </div>
{{/let}}

An important detail is that I've put ...attributes twice. Otherwise, if put it into <input only, we would break the web component, cause there is no reliable way to style it anymore, since our component doesn't recognize any attributes passed. There is no any built-in HTML tag or CustomElement which wouldn't render an attribute you pass into it. That's why I say, ...attributes at the outer-most element is a must for any component.

Back to our InputWithAttributes. We can invoke it like that:

<InputWithAttributes
  @label="Label"
  {{on "input" this.updateValue}}
  value={{this.value}}
  id="1"
/>

and the output looks fine:

<div class="InputWithAttributes" id="1">
  <label for="ember170">Label</label>
  <input id="ember170" class="InputWithAttributes-input">
</div>

We've even managed input's id to have a priority over id passed from outside by tweaking ...attributes order on <input. However, now we have problem with modifiers. Once I edit input, it's being called twice for obvious reasons.

Now, if we try to pass a class

<InputWithAttributes
  @label="Label"
  {{on "input" this.updateValue}}
  value={{this.value}}
  class="App-input"
  id="1"
/>

A passed App-input would appear twice as well because of class merging behavior:

<div class="InputWithAttributes App-input" id="1">
  <label for="ember169">Label</label>
  <input class="App-input InputWithAttributes-input" id="ember169">
</div>

To be clear, it isn't related to classes merging behavior. If I pass any custom attribute which we haven't blacklisted explicitly, for instance data-test it would also appear twice.

I'd say this issue is similar to breaking ...attributes in the outer element. In both cases we make styling and testing much more tricky.

[pzuraq]

However, now we have problem with modifiers. Once I edit input, it's being called twice for obvious reasons.

I personally think that using modifiers with components is, if not an antipattern, definitely something that should not be the main API for interacting with any component, regardless of whether or not ...attributes is on the top element. We have arguments and actions for a reason - the main APIs for interacting with a component should always be arguments and actions.

The internal details of how event listeners are added and elements are handled should not be something that your external code cares about. Otherwise you've already broken encapsulation, and you're going to be facing refactoring hazards no matter what.

An important detail is that I've put ...attributes twice. Otherwise, if put it into <input only, we would break the web component, cause there is no reliable way to style it anymore, since our component doesn't recognize any attributes passed. There is no any built-in HTML tag or CustomElement which wouldn't render an attribute you pass into it. That's why I say, ...attributes at the outer-most element is a must for any component.

This seems to point toward a need for more flexibility with ...attributes, not less. In components like this, it may make sense to split the attributes such that specific attrs are applied to the input, and the rest are applied to the wrapping element, or vice-versa. I actually think while a few key elements like class would probably want to be applied to the wrapper, you would actually want to spread the remainder into the input directly, since it's the more customizable element.

[ro0gr]

regardless of whether or not ...attributes is on the top element

I think that's the main confusion point, which is probably a root cause of the ticket.

Even <br preserves any attributes passed in:

<br id="nice-one" wherever="whatever" />

<script>
  document.querySelector('nice-one');
  hr.getAttribute("wherever"); // "whatever" 
</script>

If we allow the component's root to ignore passed attributes, such a component would break my expactations about output it produces. That's not aligned with what I've learned about HTML for years.

it may make sense to split the attributes such that specific attrs are applied to the input, and the rest are applied to the wrapping element, or vice-versa. I actually think while a few key elements like class would probably want to be applied to the wrapper, you would actually want to spread the remainder into the input directly

I'm curious is there a reason to remove attrs from the root at all?

In general, after some more thinking about the input case, and discussions, I think I'm finally convinced about usefulness of picking specific attributes somewhere deep in the component, but please, not vice versa! 😄

---

That's probably not a topic of the ticket, but what about:

  <div class={{scope}} ...attributes>
    
    <input
      readonly
      autocomplete="off"
      ...attributes
      id={{this.inputId}}
      class="{{scope}}-input"
    >

With that syntax, to the element would be applied only those attrs which are listed before the ...attributes.

The rules are stupid simple:

• if there is only a key(e.g. readonly) and no such attribute available in the ...attributes, the key is being removed(this is the only new rule). Otherwise, it gets initialized with the value from ...attributes
• if there is a value(e.g. autocomplete="off"), it just works like today. So the value from ...attributes takes precedence.

upd: well, seems like these rules break the root element's ...attributes, though it still feels close to a solution to me 🤔