feat: readme

README.md

@@ -1,16 +1,161 @@
 # flutter_shopping
 
-This component contains TODO...
+The flutter_shopping user-story allows you to create an user shopping flow within minutes of work. This user-story contains the ability to show products, shopping cart, gathering user information and order succes and failed screens.
 
-## Features
+## Setup
 
-* TODO...
+(1) Set up your `MyShop` model by extending from the `ProductPageShop` class. The most basic version looks like this:
+
+```dart
+class MyShop extends ProductPageShop {
+  const MyShop({
+    required super.id,
+    required super.name,
+  });
+}
+```
+
+(2) Set up your `MyProduct` model by extending from `ShoppingCartProduct` and extending from the mixin `ProductPageProduct`, like this:
+
+```dart
+class MyProduct extends ShoppingCartProduct with ProductPageProduct {
+  MyProduct({
+    required super.id,
+    required super.name,
+    required super.price,
+    required this.category,
+    required this.imageUrl,
+    this.discountPrice,
+    this.hasDiscount = false,
+  });
+
+  @override
+  final String category;
+
+  @override
+  final String imageUrl;
+
+  @override
+  final double? discountPrice;
+
+  @override
+  final bool hasDiscount;
+}
+```
+
+(3) Finally in your `routes.dart` import all the routes from the user-story:
+
+```dart
+...getShoppingStoryRoutes(
+    configuration: ...
+),  
+```
+
+(4) Create a new instantiation of the ProductService class:
+
+```dart
+final ProductService<MyProduct> productService = ProductService([]);
+```
+
+(5) Set up the `FlutterShoppingConfiguration`:
+
+```dart
+FlutterShoppingConfiguration(
+    // (REQUIRED): Shop builder configuration
+    shopBuilder: (BuildContext context) => ProductPageScreen(
+        configuration: ProductPageConfiguration(
+            // (REQUIRED): List of shops that should be displayed
+            // If there is only one, make a list with just one shop.
+            shops: getShops(),
+
+            // (REQUIRED): Function to add a product to the cart
+            onAddToCart: (ProductPageProduct product) =>
+                productService.addProduct(product as MyProduct),
+
+            // (REQUIRED): Function to get the products for a shop
+            getProducts: (String shopId) => Future<ProductPageContent>.value(
+                getShopContent(shopId),
+            ),
+
+            // (REQUIRED): Function to navigate to the shopping cart
+            onNavigateToShoppingCart: () => onCompleteProductPage(context),
+
+            // (RECOMMENDED) Function that returns the description for a
+            // product that is on sale.
+            getDiscountDescription: (ProductPageProduct product) =>
+                """${product.name} for just \$${product.discountPrice?.toStringAsFixed(2)}""",
+
+            // (RECOMMENDED) Function that is fired when the shop selection
+            // changes. You could use this to clear your shopping cart or to
+            // change the products so they belong to the correct shop again.
+            onShopSelectionChange: (shopId) => productService.clear(),
+
+            // (RECOMMENDED) The shop that is initially selected.
+            // Must be one of the shops in the [shops] list.
+            initialShop: getShops().first,
+
+            // (RECOMMENDED) Localizations for the product page.
+            localizations: const ProductPageLocalization(),
+
+            // (OPTIONAL) Appbar
+            appBar: ...
+        ),
+    ),
+
+    // (REQUIRED): Shopping cart builder configuration
+    shoppingCartBuilder: (BuildContext context) => ShoppingCartScreen(
+        configuration: ShoppingCartConfig(
+            // (REQUIRED) product service instance:
+            productService: productService,
+
+            // (REQUIRED) product item builder:
+            productItemBuilder: (context, locale, product) => ...
+
+            // (OPTIONAL/REQUIRED) on confirm order callback:
+            // Either use this callback or the placeOrderButtonBuilder.
+            onConfirmOrder: (products) => onCompleteShoppingCart(context),
+
+            // (RECOMMENDED) localizations:
+            localizations: const ShoppingCartLocalizations(),
+
+            // (OPTIONAL) custom appbar:
+            appBar: ...
+        ),
+    ),
+
+    // (REQUIRED): Configuration on what to do when the user story is
+    // completed.
+    onCompleteUserStory: (BuildContext context) {
+        context.go(homePage);
+    },
+
+    // (RECOMMENDED) Handle processing of the order details. This function
+    // should return true if the order was processed successfully, otherwise
+    // false.
+    //
+    // If this function is not provided, it is assumed that the order is
+    // always processed successfully.
+    //
+    // Example use cases that could be implemented here:
+    // - Sending and storing the order on a server,
+    // - Processing payment (if the user decides to pay upfront).
+    // - And many more...
+    onCompleteOrderDetails:
+        (BuildContext context, OrderResult orderDetails) async {
+            ...
+    },
+)
+```
+
+For more information about the component specific items please take a look at their repositories:
+
+- [flutter_product_page](https://github.com/Iconica-Development/flutter_product_page/)
+- [flutter_shopping_cart](https://github.com/Iconica-Development/flutter_shopping_cart)
+- [flutter_order_details](https://github.com/Iconica-Development/flutter_order_details)
 
 ## Usage
 
-First, TODO...
-
-For a more detailed example you can see the [example](https://github.com/Iconica-Development/flutter_shopping/tree/main/example).
+For a detailed example you can see the [example](https://github.com/Iconica-Development/flutter_shopping/tree/main/example).
 
 Or, you could run the example yourself:
 ```