docs(cart): clean up formatting of existing cart documentation

libs/cart/README.md

@@ -1,4 +1,115 @@
 # @daffodil/cart
-
 Building and maintaining a model and code for an ecommerce store is complex and mentally taxing. `@daffodil/cart`
 provides clear interfaces, models, and factories for the frontend of an ecommerce store so that you don't have to.
+
+## Installation
+To install the cart library and its dependencies, use the following commands in the terminal.
+
+Install with npm:
+```
+npm install @daffodil/cart @daffodil/core @ngrx/store @ngrx/effects --save
+```
+
+Install with yarn:
+```
+yarn add @daffodil/cart @daffodil/core @ngrx/store @ngrx/effects
+```
+
+## Getting started
+The cart module includes multiple layers of functionality that build on each other. The models can be used on their own. The driver layers can be used with the models but also allow custom extensions to those models to be passed as generics. A state layer sits on top of the driver layer. Individual drivers can be overridden through driver injection tokens and custom extensions to models can be passed into the state layer's generics.
+
+The recommended way to use Daffodil is with the state layer.
+
+- [State guide](/libs/cart/guides/state.md)
+- [Drivers guide](/libs/cart/guides/drivers.md)
+- [Extension guide](/libs/cart/guides/extension.md)
+
+## Usage
+
+### Interacting with platforms
+Interacting with platforms through the [cart facade](/libs/cart/guides/state.md#using-the-facade) is the recommended method.
+
+It is possible to interact with platforms by directly calling the drivers. While this requires more work to integrate into components, it offers greater flexibility. See the [drivers guide](/libs/cart/guides/drivers.md) for more information.
+
+### Using routing guards
+The cart module provides a number of routing guards to prevent access to certain pages until specific data becomes available.
+
+The following example illustrates using the `DaffShippingAddressGuard` to prevent accessing the shipping method page of checkout until a shipping address has been set.
+
+```ts
+import {
+  DaffShippingAddressGuard,
+  DaffCartShippingAddressGuardRedirectUrl
+} from '@daffodil/cart';
+
+@NgModule({
+  imports: [
+    ...,
+    RouterModule.forRoot([
+      {
+        path: 'checkout/shipping',
+        component: CheckoutShippingComponent,
+        canActivate: [DaffShippingAddressGuard]
+      },
+      {
+        path: '',
+        component: HomepageComponent,
+      },
+    ])
+  ],
+  providers: [
+    {
+      provide: DaffCartShippingAddressGuardRedirectUrl,
+      useValue: '/'
+    }
+  ]
+})
+class AppModule {}
+```
+
+> The `'checkout/shipping'` route's activation was guarded with the `DaffShippingAddressGuard`, ensuring that page cannot be accessed unless the cart has a valid shipping address set. The `DaffCartShippingAddressGuardRedirectUrl` token is used to configure the path to which the user is redirected when and if the activation fails.
+
+### Providing platform-agnostic payment IDs
+The cart facade provides a field (`paymentId$`) for agnostic payment IDs. The IDs must be user-supplied to prevent circular package dependencies. Provide an object for the `DaffCartPaymentMethodIdMap` token. The keys of this object should be cart payment methods and the values should be strings.
+
+```ts
+import {
+  DaffCartPaymentMethodIdMap,
+  DaffCartFacade,
+  DaffCartPaymentMethod
+} from '@daffodil/cart';
+
+@NgModule({
+  ...,
+  providers: [
+    {
+      provide: DaffCartPaymentMethodIdMap,
+      useValue: {
+        authorizenet_accept_js: 'authorizenet',
+        payflowpro: 'paypal'
+      }
+    }
+  ]
+})
+class AppModule {}
+
+@Component({})
+class CartComponent implements OnInit {
+  paymentID$: Observable<string>;
+
+  constructor(private cartFacade: DaffCartFacade) {}
+
+  ngOnInit() {
+    this.paymentID$ = this.cartFacade.paymentId$;
+  }
+
+  setPayment(info) {
+    this.cartFacade.dispatch(new DaffCartPaymentUpdate({
+      method: 'authorizenet_accept_js',
+      payment_info: info
+    }));
+  }
+}
+```
+
+> When `setPayment` is called, the cart payment method will be updated. After this update is finished, the `this.paymentID$` stream will emit `'authorizenet'`.

libs/cart/guides/drivers.md

@@ -1,17 +1,16 @@
 # Drivers
+The cart module can interface with supported platforms through drivers. Choose the driver that corresponds to the platform of choice and follow the linked guide to set it up.
 
-Daffodil can interface with supported platforms through drivers. Choose the driver that corresponds to the platform of choice and follow the linked guide to set it up.
+## Supported drivers
 
-## Supported Drivers
-
-### In-Memory Web API
-
-The In-Memory driver is for rapid development without the need to set up a magento/shopify/etc backend. It will mock out the management of a cart and operate like a functional backend. It is intended for development and testing purposes; it is not meant to be used in production.
+### In-Memory web API
+The In-Memory driver is for rapid development without the need to set up a magento/shopify/etc backend. It will mock out the management of a cart and operate like a functional backend. It is intended for development and testing purposes and not meant to be used in production.
 
 To set up, import the `DaffCartInMemoryDriverModule` from the `@daffodil/cart/testing` library and the `HttpClientInMemoryWebApiModule` from `angular-in-memory-web-api`.
- Include `DaffCartInMemoryDriverModule.forRoot()` and `HttpClientInMemoryWebApiModule` in the imports section of `AppModule`.
 
-```typescript
+Include `DaffCartInMemoryDriverModule.forRoot()` and `HttpClientInMemoryWebApiModule` in the imports section of `AppModule`.
+
+```ts
 import { HttpClientInMemoryWebApiModule } from 'angular-in-memory-web-api';
 import { DaffCartInMemoryDriverModule } from '@daffodil/cart/testing';
 
@@ -24,18 +23,18 @@ import { DaffCartInMemoryDriverModule } from '@daffodil/cart/testing';
 export class AppModule {}
 ```
 
-Now this `DaffCart` implementation will have access to the In-Memory Driver to use while developing.
+Now this `DaffCart` implementation will have access to the In-Memory driver to use while developing.
 
-> It is important to note to only have one `daffodil/cart` driver set up in `AppModule` at a time. To set up a driver configuration to make switching between different backend drivers simple, follow the [advanced setup guide](). <!-- TODO: add multiple drivers guide -->
+> Note: It is important to only have one `daffodil/cart` driver set up at a time in the `AppModule`. To set up a driver configuration to make switching between different backend drivers simple, follow the [advanced setup guide](). <!-- TODO: add multiple drivers guide -->
 
 ### Magento
-
 The Magento driver communicates with the Magento backend through the GraphQL API.
 
 To set up, import the `DaffCartMagentoDriverModule` from the `@daffodil/cart` library and the `ApolloModule` from `apollo-angular`.
- Include `DaffCartMagentoDriverModule.forRoot()` and `ApolloModule` in the imports section of `AppModule`.
 
-```typescript
+Include `DaffCartMagentoDriverModule.forRoot()` and `ApolloModule` in the imports section of `AppModule`.
+
+```ts
 import { ApolloModule } from 'apollo-angular';
 import { DaffCartMagentoDriverModule } from '@daffodil/cart';
 
@@ -48,19 +47,17 @@ import { DaffCartMagentoDriverModule } from '@daffodil/cart';
 export class AppModule {}
 ```
 
-Now this `DaffCart` implementation will be able to interact with Magento.
-
-> It is important to note to only have one `@daffodil/cart` driver set up in `AppModule` at a time. To set up a driver configuration to make switching between different backend drivers simple, follow the [advanced setup guide](). <!-- TODO: add multiple drivers guide -->
+This `DaffCart` implementation will now be able to interact with Magento.
 
-#### Fragment Introspection
+> Note: It is important to only have one `@daffodil/cart` driver set up in `AppModule` at a time. To set up a driver configuration to make switching between different backend drivers simple, follow the [advanced setup guide](). <!-- TODO: add multiple drivers guide -->
 
-You should set up fragment introspection with the Magento backend. Refer to the [fragment introspection guide](../../../../tools/builders/guides/fragment-introspection.md) for more info.
+#### Fragment introspection
+You should set up fragment introspection with the Magento backend. Refer to the [fragment introspection guide](../../../../tools/builders/guides/fragment-introspection.md) for more information.
 
 ## Usage
-
 The drivers can be injected into components and invoked directly. The following example shows how to list the items in the cart and add a simple item to the cart.
 
-```typescript
+```ts
 import {
   DaffCartItemServiceInterface,
   DaffCartItemDriver,

libs/cart/guides/extension.md

@@ -1,14 +1,12 @@
 # Extension
+The cart module provides a number of extension mechanisms so that it can be customized to fit specific needs.
 
-`@daffodil/cart` provides a number of extension mechanisms so that it can be customized to fit specific needs.
-
-## Custom Drivers
-
+## Custom drivers
 If the packaged Daffodil drivers don't satisfy the required use cases, they can be overriden by providing custom drivers. Create a service that implements the interface corresponding to the driver in question.
 
 If custom behavior is not needed for all driver methods, unimplemented methods can be delegated to the original driver. The following example demonstrates overriding the `create` method of the `DaffCartDriver` while using Magento.
 
-```typescript
+```ts
 import {
   DaffCartDriver,
   DaffMagentoCartService
@@ -51,11 +49,10 @@ export class CustomMagentoCartService implements DaffCartServiceInterface {
 class AppModule {}
 ```
 
-## Generic Models
-
+## Generic models
 All Daffodil layers can operate on generic extensions of vanilla Daffodil models. Custom models can therefore be used while retaining type safety. The following example illustrates customizing the cart model with the cart facade.
 
-```typescript
+```ts
 import {
   DaffCartFacade,
   DaffCart
@@ -78,22 +75,21 @@ class CartComponent implements OnInit {
 }
 ```
 
-## Extensible GraphQL Fragments
-
+## Extensible GraphQL fragments
 Arbitrary additional fields can be requested on the cart object. Inject a GraphQL document node containing fragments on the platform's cart type to define extra fields.
 
 Only drivers that use GraphQL support extensible fragments because fragments are specific to GraphQL. The following cart drivers support extensible fragments:
+
 - Magento
 
 ### Magento
-
 Provide the `DAFF_CART_MAGENTO_EXTRA_CART_FRAGMENTS` to query additional fields on a Magento cart query. This applies to all of the driver calls that return a `DaffCart`, which is most of them.
 
 The additional fields are present on the untyped `extra_attributes` field.
 
 The following example demonstrates providing a GraphQL document using the `graphql-tag` library.
 
-```typescript
+```ts
 import gql from 'graphql-tag';
 import {
   DAFF_CART_MAGENTO_EXTRA_CART_FRAGMENTS,