[Addressbook part 2] Complete the UI by allowing choice between multiple addressbook profiles

Spun out a portion to #3055035: Finalize the AddressBookManager service. Going to land that first.

EDIT: Done.

Here's an initial implementation of the 2.x UX. Screenshot also attached.

The UX is simple, there is a "Select an address" dropdown that pre-fills the form. Selecting "+ Enter a new address" gives you an empty form.
The dropdown is not there if the profile type only allows a single profile per customer.

The point of this patch is to help the Commerce team choose the right UX. It is not commit ready.

The 3.x UX patch will follow shortly.

For the sake of history, I am posting the last 2.x UI patch that we tested. Compared to the one in #3 it contains a few code cleanups, bug fixes, and makes the "copy" checkbox also visible for the "edit" use case (when an existing address book profile is selected).

We have decided against proceeding with the 2.x UI because it makes it difficult to differentiate between the "edit" and "add" operations.
Consider this:
- Customer hits checkout. Previous address is selected.
- Customer enters new address, without choosing "Enter a new address" from the dropdown
- Customer completes checkout.

There are two outcomes of this, depending on whether the customer checked the "Update my stored address" checkbox:
a) The new address has replaced the other one in the address book.
b) The new address wasn't entered into the address book at all.
Neither feels optimal. Yes, we could decide to treat the "edit" as "add" based on some magic criteria (did the address_line1 change? etc), but now we're guessing.

This is why we're proceeding with the 3.x UI, which is very similar code-wise. More on that in another comment.

I committed #3065400: Allow AddressBook::copy() to update address book profiles separately to reduce the size of this patch, but it's still huge.
It has gone through several major iterations. Most of the unplanned, additional work came from applying the address book to the admin pages, which is something that the D7 version didn't support.

This is easily the hardest work I've done in the 2.x cycle. The number of code paths through the UI is huge (anonymous VS authenticated customer, admin VS checkout, single VS multiple mode, add VS edit, etc), so it required extensive test coverage (mostly done in CustomerProfileTest). We repeat a lot of that coverage in PaymentCheckoutTest, ensuring that in a real checkout an address can be reused, edited, or replaced.

Any site running Shipping will need to update to today's -dev, because I just committed #3054351: Add support for the Commerce 2.14 address book there.
You also need a recent -dev of Profile.

Crediting jsacksick, mglaman, rszrama, who have spent significant time discussing and reviewing the patches.

Retitling, since we're finishing this before #2910193: Allow reusing profile values from another inline form ("Billing same as shipping").

Here is a green patch, along with some screenshots.

We have two modes, activated via the profile type checkbox "Allow multiple profiles per user".
1) Single - Provided in D7 by the Commerce Single Address module. The customer always has a single address book profile. This address book profile always reflects the last entered address (there is no checkbox to opt out of copying). Commonly used for billing information on some sites, especially ones that sell digital products (e.g. Platform.sh).

When in admin mode (admin order/shipment UIs), the copy checkbox is shown and unchecked: "Save to the customer's address book" / "Also update the address in the customer's address book". This allows admins to create orders with one-off addresses.

2) Multiple - Default. Provided in D7 by the Commerce Address Book module. The customer can have multiple address book profiles, selected via dropdown. When the "+ Enter a new address" option is selected, a "Save to my address book" checkbox is shown, to allow the customer to add a one-off address, or add it to the address book. The "edit" flow will of course update the address book profile, no checkbox is shown in that case cause the intent is obvious.

When in admin mode (admin order/shipment UIs), the copy checkbox shown when adding a new address will say "Save to the customer's address book", and unchecked. If editing a profile that was already added to the address book, and the two profiles are still identical, the address book profile will be updated.

Additional touches:
- Assume that a profile was added to the address book for the address "9 Drupal Ave". After that, the address book profile was edited via the user pages, and its phone number was updated. Editing the main profile (on the order / payment method) will now show two options: "9 Drupal Ave (original version)" and "9 Drupal Ave (updated version)". This allows the customer to retain the previous information (and even update it further), or to switch to the latest version of the profile (thus removing the original version).

The main thing to note in the screenshots above is that once you click "Edit", you get a form, with no Save / Cancel buttons.
We did this to (significantly) simplify the code and to reduce the number of interactions the customer can have. I experimented with having just a Cancel button, like the D7 address book had, but it felt potentially dangerous (someone enters an address and clicks the button below out of habit, boom, changes lost).

If you select a different address in the dropdown, that resets the UI to render mode.

That's the main thing we need to agree on, whether it is okay to not have Save / Cancel buttons.
Naturally, people who end up not liking this UI will be able to swap out the CustomerProfile inline form plugin, but I still want the default UX to have a broad consensus.

In multiple mode you can also toggle the dropdown (select a different address, then the previous one again).
However, the profile form is generally short enough that I don't see reverting as a major requirement.

Thanks for the review!

First of all: the implementation really seems to be solid. I've continued several time to next step and then went back, did some changes, etc. And all seemed fine.

That's great to hear. We've done a lot of testing and debugging internally before posting the patch.

when I select an address from my address book and then edit it - should we add a checkbox on whether to sync changes to the stored address? ok, it's in the patch I see ("Also update the address in my address book").. hmm now I'm unsure, if I've just overseen this, or if it was missing!? Could someone plz test this?

The checkbox is there, checked but hidden. If you're editing an address book profile we assume that clicking "Edit" communicates enough intent that we can assume we're always copying. Of course, if the edited profile has drifted from the address book profile (and has an "original value" suffix), the copy checkbox is off (but still hidden). That way we don't ask questions we know the answer to.

in the dropdown, should we add postal code + locality to the label, or keep only the street address? Of course, it won't happen often, that you have stored addresses in different cities with the same street name, but it felt a little bit unusual to only choose a street name from a list. but that's a matter of taste for sure

Good question. This was also raised in internal review. Opened #3067030: Expand the default profile label (currently: address_line1) with some initial thoughts.

we have added an additional field to the profile (phone number). The copy checkbox was placed after the address, but before the phone number field, which is bad. Maybe we should add quite a high weight to the checkbox, so that this won't happen under normal circumstances?

Nice catch. I'll add a large #weight in the next/final reroll.

@Jons
You'll probably want to copy the CustomerProfile inline form class into your own module, and customize it there (point the plugin definition to it via hook_commerce_inline_form_info_alter()). I'm expecting you'd need/want to do significant changes to the logic, which would be tricky to do from a form alter hook.

@Jons
Each parent entity (order, payment method) must get its own profile to protect against modification. That's what allows you to delete an address book profile without affecting existing orders and payment methods. And that's what allows you to modify one order's address without modifying all of them. Our payment methods should map 1-1 to Stripe payment methods, where addresses aren't a standalone object, so we should be fine.

Okay, since the initial reviews were positive, I'm going ahead and committing #13, with two additional changes:
1) Require a stable version of Profile again, now that we've tagged RC6
2) Add #weight to the select_address and copy_to_address_book elements.

We discussed #22 and thought that the feedback was valid but were unsure about the naming changes, so we decided to wait for more feedback.

Let's continue testing -dev. I won't tag 2.14 for another week. Thanks, everyone!

Immediate next focus: Finishing #3059633: Provide a better addressbook UI for the user pages.

Why report it here? Wrong module

@NicolasGraph
Never tried it, but my gut tells me that a form alter is too late for swapping out the inline form. You'd need to override the checkout pane and do it there.

Personally I'd still swap out the CustomerProfile inline form, inherit from it, check for $this->configuration['admin'], which indicates backend usage, and in that case fall back to the parent implementation:

$inline_form = parent::buildInlineForm($inline_form, $form_state);
if ($this->configuration['admin']) {
  // Use the parent logic.
  return $inline_form;  
}
else {
  // Do our thing.
}

In the CustomerProfile at line 170, $triggering_element is not defined.

Thanks for catching this, opened #3068649: Undefined variable $triggering_element in CustomerProfile::buildInlineForm().

Also, shouldn't we unset the 'revision_log_message' item of the profile forms on the front-end ?

Yes: #3061017: Remove the revision_log_message field in CustomerProfile.