docs: Document re-rendering based on complex data.

[Kelketek]

(Re-opened since #190 was forcibly auto-closed by the target merge branch being deleted)

This PR adds documentation on rendering limitations as they pertain to complex data structures. It also makes some minor typographical adjustments found along the way.

cc @theengineear @klebba

[theengineear]

Hey @Kelketek! I think my feedback here is that we should advocate for the use of referential updates in integration code (versus advocating for imperative alternatives).

[theengineear]

My high-level feedback is that the x-element documentation ought to advocate for consistently leveraging change-by-reference detection patterns.

I.e., rather than say “if you use a compound object, you need to do extra imperative calls when you mutate the data” — we should say “mint new object references versus mutating data in place”.

Object / array spread operators make this pretty straightforward in modern JS. The bet is that the cost (both performance and complexity) is cheaper to simply update object references when binding properties (versus encoding and performing many imperative calls to mutate DOM).

[Kelketek]

@theengineear I've updated the docs to avoid mentioning the imperative re-rending method, and have made it clear that change-by-reference is recommended.

[theengineear]

Sorry to be nit-picky! I think I understand the sentiment that you’re trying to land in here, but I’m just trying to find the right way to help you convey it. I left a counter-proposal for you in a review comment 🤘

[theengineear]

I think the language around “web components” is still a little too loose — this is more about template engines IMO. Rather than go back-and-forth, how about I just draft up a quick counter-proposal for you? Thoughts?

---

A note on non-primitive data:

Because DOM manipulation is slow — template engines do their best to avoid it (if a value hasn’t changed, DOM manipulation is skipped). To know if a non-primitive property has changed, a change-by-reference check is performed (versus a change-by-value check). Therefore treat non-primitives as if they’re immutable. I.e., do this: element.property = { ...element.property, foo: 'bar' }. And don’t do this: element.property.foo = 'bar'.

[Kelketek]

@theengineear Thanks-- yes, some of the boundaries are still fuzzy to me since this project is my first use of web components. I was on the fence about writing something on the lines of 'treat non-primitives as though they're immutable', even though I was understanding this to be the implication, because that almost seemed like something that should be discussed in the design philosophy section, but I couldn't think of a way to fit it in there.

I'll think a bit more on whether there's a better way to communicate the expected design patterns this library is hoping to encourage. Although, it might be obvious to people who know they need it.

In any case, I made a couple of small grammatical changes to the suggested replacement, rebased and squashed. Should be ready for you, thanks!