shopping_list_guide.md: details, screenshots, extensibility

Author: adriendupuis

docs/commerce/shopping_list/img/create_from_management.png

@@ -6,7 +6,7 @@ month_change: true
 
 # Shopping list feature guide
 
-Shopping lists give customers a simple yet powerful way to manage future purchases.
+Shopping lists give logged-in customers a simple yet powerful way to manage future purchases.
 It can cover many purchase planning cases.
 
 ## Use cases
@@ -29,28 +29,43 @@ even several products fulfilling the same purpose to decide latter wish ones to
 
 Policies can give the rights to create, view, edit, and delete shopping lists.
 Authenticated customers can be granted with those rights on their own shopping lists.
+For more information, see [Shopping list user role](install_shopping_list.md#shopping-list-user-role).
 
-Such customer can
+A customer always have a default shopping list named "My Wishlist"
+which is created automatically on first use,
+which can't be renamed, and can't be deleted.
+According to configuration, customers can have a limited amount of additional custom shopping lists.
+The number of products a shopping list can contain is also limited by configuration.
+
+A shopping list only stores product codes.
+A shopping list doesn't store quantities.
+
+In the out-of-the-box storefront, a shopping list user can:
 
 - Create a shopping list
     - in shopping lists management interface
+      ![Shopping lists management interface with an highlight on the "Create" button](img/create_from_management.png "Create a new shopping list from the shopping lists management interface")
     - from catalog when adding a product to a shopping list
-    - from cart when saving for later into a shopping list
+      ![Product "Add to cart" button and "Add to list" drop-down menu zone with an highlight on the "+ Create an new shopping list" option](img/create_from_product.png "Create a new shopping list from the product page")
+    - from a shopping list when moving products from one shopping list to another
+      !["Move to another list" pop-in with an highlight on the "+ Create a new shopping list" option](img/create_from_move.png "Create a new shopping list from the move target selection interface")
 - Add product (or product variant) to a shopping list
 - Rename a shopping list (except the default "My Wishlist")
-- List existing shopping lists
-- View a shopping list product list
+- View the list of their shopping lists
+- View a shopping list and its product list
 - Move products from a shopping list to another shopping list
-- TODO: Copy products from a shopping list to another shopping list
 - Remove product from a shopping list
-- Clear all products from a shopping list
-- Copy product from a shopping list to cart (products are kept in shopping list while added to the cart)
+- Copy product from a shopping list to cart (product is kept in shopping list while added to the cart)
 - Copy a whole shopping list to cart (products are kept in shopping list while added to the cart)
-- Move products from cart to a shopping list (product are removed from cart and added to the shopping list)
+    - products are kept in shopping list while added to the cart
+    - products out-of-stock aren't copied and the user is warned
+    - products are added with quantity 1, the user can adjust quantities in the cart afterward
 - Move a whole cart to a shopping list (products are removed from cart and added to the shopping list)
 - Delete a shopping list
 
-A shopping list only stores product codes.
-A shopping list doesn't store quantities.
+## Extensibility
+
+The [PHP API](shopping_list_api.md#php-api) and the [REST API](shopping_list_api.md#rest-api) already offers few functionalities not used in the default storefront,
+such as to empty a whole shopping list, or to copy products from a shopping list to another (instead of moving them).
 
-TODO: illustrate with storefront screenshots?
+Those APIs can be used to implement custom features, and can themselves be extended to cover more use cases.