[docs] Improve wording for animate docs, refs #6807
#6813
Conversation
Quoting sveltejs#6807 > Usually when you add or remove an item from a list, you don't consider this a "re-order". Yes, technically all elements after the new/removed element change their position within the list, but the order is exactly the same. If you stand in line for coffee and the person in front of you gets a call and leaves you wouldn't say the order of the line changed. I'm not a native speaker though shrug
| @@ -1132,7 +1132,7 @@ DOMRect { | |||
|
|
|||
| --- | |||
|
|
|||
| An animation is triggered when the contents of a [keyed each block](docs#each) are re-ordered. Animations do not run when an element is removed, only when the each block's data is reordered. Animate directives must be on an element that is an *immediate* child of a keyed each block. | |||
| An animation is triggered when an element inside a [keyed each block](docs#each) changes its position. Animations do not run for newly added or removed elements. They only run when the data of an existing element changes position within the each block's data. Animate directives must be on an element that is an *immediate* child of a keyed each block. | |||
There was a problem hiding this comment.
I have to say I'm not a big fan of this change. The passive voice sounds odd, it's more verbose, and it doesn't mean anything different to me
There was a problem hiding this comment.
Maybe (versus the original one) "Animations do not run when an element is added or removed" (adding the bit about "added or")? I agree that the suggested changes here don't bring much that's new.
There was a problem hiding this comment.
it doesn't mean anything different to me
I agree that the suggested changes here don't bring much that's new.
My main point is to remove the "are re-ordered" part. Because that threw me off and I assumed animate only runs when the order of the elements changes. Maybe this is a language barrier, but to me "order" (related to the term "sort order") is defined by the comparator function or some intrinsic property of the list. If I remove an element from the list then nothing is re-ordered. The order does not change.
But like I said, I'm not a native speaker and the only time I come across the term "order" is in a programming/cs context (but I'm aware that there are other orders, such as in a military context or when I order something online, that are entirely unrelated)
The docs say:
Animations do not run when an element is removed
But they do. The current wording uses the plural form "Animations" when in reality each animation has to be looked at in isolation (because the logic only looks if the index of a given element has changed, ignoring anything around it). Because yes, when an element is removed the animations (plural) do run, but not the animation (singular) of the removed element. Only those animations of elements that come after run.
I assume it is worded this way because the original author knew about transitions and maybe it is worded this way in comparison to transitions (which run when elements are created/removed). But without the transition knowledge the animation paragraph is misleading.
There was a problem hiding this comment.
How about something like this?
Animations do not run when an element is added or removed, only when the index of a data item within the each block is changed
|
I simplified it via @benmccann's suggestion. It's now clear that it doesn't run for added elements either, not just for removed elements. And it makes clear the the index of an existing item needs to change for it to trigger an animation. |
Quoting #6807
Before submitting the PR, please make sure you do the following
[feat],[fix],[chore], or[docs].