[Documentation] Give some guidance about when to use key in the each template helper

[jenweber]

This ticket needs discussion before it can be worked on.

📙 Describe the Issue

It is important to use key with the each template helper under the following conditions, however we are missing that guidance from the API docs:

• If you are using immutable data patterns, use key. (if you are setting the array to a new array). The ID of the items will change. (if you are using a tracked array that is not an Ember Array)

It is not needed if you:

• push objects into the array, using Ember.Array

The docs we write should guide people towards using key, not push people towards Ember.Array

The API docs should give a general rule to follow: if you are iterating over something interactive/over a tracked property, use key. Then the API docs should give a more specific rule as described above. We want someone to succeed even if they don't understand the whole picture.

Why is this important?

This is an accessibility and UX concern. Focus management breaks down if you don't use key when it is needed, since object identities change.

Open questions

Is there a reason to not use key all the time? If the key is expensive to compute, that would cause a problem. However you can make anything in Ember expensive to render, so this may not be something we need to try and control, rather just mention the concern to users.

Does this ticket align with framework core team vision & understanding of this feature?

Related issues

In the Guides: ember-learn/guides-source#1776

[jenweber]

@mansona do you still want to reach out to the framework team about this, to see if this aligns with their vision?

[bertdeblock]

We could also link to the following template lint rule(?):
https://github.com/ember-template-lint/ember-template-lint/blob/master/docs/rule/require-each-key.md

We use Apollo at work instead of Ember Data and this lint rule has been useful for us.

[jenweber]

This is super helpful, thank you! We can at least borrow from some of this content.