Improve using elements in lists

[kyleve]

This PR changes the recommended way to convert Blueprint Elements into Items or HeaderFooters. The old way was to either manually define a BlueprintItemContent or BlueprintHeaderFooterContent, which worked great for more complex needs, or to use the ElementItem(...) or ElementHeaderFooter(...) funcs, which were meant for simpler use cases. However, the latter was still pretty wordy, and people would still regularly mess it up.

Here, we instead add extensions to Element to support both Item and HeaderFooter use cases: You can just directly return an Element anywhere an ItemContent or HeaderFooterContent was previously required (caveat: Where assignment happens directly; such as Section.header, you still need to do section.header = element.headerFooter()).

This PR also moves isEquivalent(to:) into its own interface (LayoutEquivalent), so (a) the docs can be shared, and (b) so elements can conform to it and be used in either the item or header/footer case.

TL;DR

Now that this PR exists, you can now do:

List {
   Section("some-id") {
       SomeElement()
       AnotherElement()
       SomeItemContent()
       MyCoolElement().listItem(id: "my-id") {
          $0.selectionStyle = .tappable
       }
   } header: {
      MyHeaderElement()
   } footer: {
      MyFooterElement().listHeaderFooter {
         ...
      }
   }
}

Checklist

Please do the following before merging:

• Ensure any public-facing changes are reflected in the changelog. Include them in the Main section.

[kyleve]

This was a pure dupe of the above, just with less parameters.

[kylebshr]

I think some discussion points here would be:

a) Is this an even bigger foot gun than what we have now? Many people probably won't make their element equatable or IsEquivalentItem
b) Is there a performance concern from losing identifiers (most people won't add one)
c) Most elements have closures, which make equatability impossible. What's the correct thing to do there. Should there be more helpers for interacting with the row tap handlers, so that the element doesn't have to be re-applied for the closure to be correct?

[kyleve]

@kylebshr Creating a thread to reply to stuff, so we can talk in a thread vs top level comments:

a) Is this an even bigger foot gun than what we have now? Many people probably won't make their element equatable or IsEquivalentItem

Hard to say – there's a bunch of existing ElementItem usages in POS now, and they're all pretty much wrong – the API was hard to use, so there's a lot of this:

ElementItem("formFields-element", id: \.self) { _, _ in
   // Return an element
}

ElementItem(transaction.token, id: \.self) { _, _ in ... }

ElementItem("error-state", id: \.self) { _, _ in ... }

ElementItem("business-organization-name-content", id: \.self) { _, _ in ... }

Etc...

But in this case the underlying value is "formFields-element", aka a static string; so isEquivalent always returns true, and the item will never re-size even when it should – which is already a foot gun and breaks things in weird ways.

b) Is there a performance concern from losing identifiers (most people won't add one)

Identifiers? No – the list smart enough to do a "best attempt" at creating stable identifiers when there's duplicate IDs (and identifiers are already salted with the ItemContent type), so even without explicitly provided IDs, you'll get stable IDs across updates. Eg, if this is your list, these will be the identifiers:

MyElement1() -> Identifier(MyElement1, 1)
MyElement2() -> Identifier(MyElement2, 1)
MyElement2() -> Identifier(MyElement2, 2)
MyElement1() -> Identifier(MyElement1, 2)

The main benefit to providing IDs is during mutative diffs, the list can more intelligently manage the changes.

c) Most elements have closures, which make equatability impossible. What's the correct thing to do there. Should there be more helpers for interacting with the row tap handlers, so that the element doesn't have to be re-applied for the closure to be correct?

Same thing as you'd do before with ItemContent / BlueprintItemContent; you need to manually implement Equatable or isEquivalent, and compare the equatable parameters that you can. There are some clever things we can do here to avoid needing this, but I didn't explore it: We can use mirror to find equatable parameters and compare them

[nononoah]

I agree with the core aspects of the direction here - the builders, the reversal of construction (from Item containing Element to Element modified to Item), and even some of the more controversial sugar that you've included. Thanks for backing this up with so much testing.

[JaviSoto]

Don't mind me, I was browsing Mastodon at 2am because I couldn't sleep and saw this PR and noticed a couple funny things 😄

[kyleve]

• TODO: Test this is indeed causing an error before merging.

[kyleve]

• TODO: Test this is indeed causing an error before merging.

[kyleve]

Finally getting around to landing this!