Merge pull request #71 from commerce-docs/USF-1327-checkout-container…

…s-redux

USF-1327: Checkout containers (redux)

astro.config.mjs

@@ -207,12 +207,26 @@ export default defineConfig({
             collapsed: true,
             items: [
               { label: 'Overview', link: '/dropins/checkout/' },
-              { label: 'Checkout Installation', link: '/dropins/checkout/checkout-installation/' },
-              { label: 'Checkout Initialization', link: '/dropins/checkout/checkout-initialization/' },
-              { label: 'Checkout Styles', link: '/dropins/checkout/checkout-styles/' },
-              // { label: 'Checkout Containers', link: '/dropins/checkout/checkout-containers/' },
-              // { label: 'Checkout Slots', link: '/dropins/checkout/checkout-slots/' },
-              { label: 'Checkout Functions', link: '/dropins/checkout/checkout-functions/' },
+              { label: 'Installation', link: '/dropins/checkout/installation/' },
+              { label: 'Initialization', link: '/dropins/checkout/initialization/' },
+              { label: 'Styles', link: '/dropins/checkout/styles/' },
+              { label: 'Containers',
+                collapsed: true,
+                items: [
+                  { label: 'BillToShippingAddress', link: '/dropins/checkout/containers/bill-to-shipping-address/' },
+                  { label: 'EstimateShipping', link: '/dropins/checkout/containers/estimate-shipping/' },
+                  { label: 'LoginForm', link: '/dropins/checkout/containers/login-form/' },
+                  { label: 'MergedCartBanner', link: '/dropins/checkout/containers/merged-cart-banner/' },
+                  { label: 'OrderConfirmationHeader', link: '/dropins/checkout/containers/order-confirmation-header/' },
+                  { label: 'OutOfStock', link: '/dropins/checkout/containers/out-of-stock/' },
+                  { label: 'PaymentMethods', link: '/dropins/checkout/containers/payment-methods/' },
+                  { label: 'PlaceOrder', link: '/dropins/checkout/containers/place-order/' },
+                  { label: 'ServerError', link: '/dropins/checkout/containers/server-error/' },
+                  { label: 'ShippingMethods', link: '/dropins/checkout/containers/shipping-methods/' },
+                ]
+              },
+              // { label: 'Slots', link: '/dropins/checkout/slots/' },
+              { label: 'Functions', link: '/dropins/checkout/functions/' },
             ]
           },
           {

src/content/docs/dropins/checkout/containers/bill-to-shipping-address.mdx

@@ -0,0 +1,50 @@
+---
+title: BillToShippingAddress container
+description: Configure the BillToShippingAddress container to manage and display the billing address form during checkout.
+---
+
+import OptionsTable from '@components/OptionsTable.astro';
+
+The `BillToShippingAddress` container includes a checkbox that allows users to indicate if the billing address is the same as the shipping address. If unchecked, the billing address form will be displayed.
+
+## BillToShippingAddress configurations
+
+The `BillToShippingAddress` container provides the following configuration options:
+
+<OptionsTable
+  compact
+  options={[
+    ['Option', 'Type', 'Req?', 'Description'],
+    ['hideOnVirtualCart', 'boolean', 'No', 'Hides the container if the cart is virtual.'],
+    ['onChange', 'function', 'No', 'Callback function that is called when the checkbox state changes.'],
+  ]}
+/>
+
+## Example
+
+The following example renders the `BillToShippingAddress` container on a checkout page. It includes functionality to hide the component for virtual carts and to handle changes to the billing address form visibility and validation. If the billing address form is shown, it validates the form data and updates the billing address on the cart.
+
+```ts
+import BillToShippingAddress from '@dropins/storefront-checkout/containers/BillToShippingAddress.js';
+import { render as CheckoutProvider } from '@dropins/storefront-checkout/render.js';
+
+const $billToShipping = checkoutFragment.querySelector(
+  '.checkout__bill-to-shipping'
+);
+
+CheckoutProvider.render(BillToShippingAddress, {
+  hideOnVirtualCart: true,
+  onChange: (checked) => {
+    $billingForm.style.display = checked ? 'none' : 'block';
+
+    if (!checked && billingFormRef.current) {
+      const isDataValid = billingFormRef.current.handleValidationSubmit();
+
+      setAddressOnCart(
+        { data: billingFormRef.current.formData, isDataValid },
+        checkoutApi.setBillingAddress
+      );
+    }
+  },
+})($billToShipping),
+```

src/content/docs/dropins/checkout/containers/estimate-shipping.mdx

@@ -0,0 +1,36 @@
+---
+title: EstimateShipping container
+description: Learn how the EstimateShipping container displays shipping costs during checkout.
+---
+
+import OptionsTable from '@components/OptionsTable.astro';
+
+The `EstimateShipping` container is designed to estimate and display shipping costs during the checkout process.
+
+## EstimateShipping configurations
+
+The `EstimateShipping` container is read-only, unlike the editable [`EstimateShipping`](/dropins/cart/cart-slots/#estimateshipping) container in the cart drop-in component. Initially, it displays estimated shipping costs. After a customer provides a shipping address and selects a shipping method, it shows the actual shipping cost. This container is designed to be used as a slot within the `OrderSummary` container from the cart, where the estimated shipping information is displayed.
+
+## Example
+
+The following example renders an `OrderSummary` container within a checkout page and includes a slot for estimating shipping:
+
+```ts
+import { OrderSummary } from '@dropins/storefront-cart/containers/OrderSummary.js';
+import { render as CartProvider } from '@dropins/storefront-cart/render.js';
+import EstimateShipping from '@dropins/storefront-checkout/containers/EstimateShipping.js';
+
+const $orderSummary = checkoutFragment.querySelector(
+  '.checkout__order-summary'
+);
+
+CartProvider.render(OrderSummary, {
+  slots: {
+    EstimateShipping: (esCtx) => {
+      const estimateShippingForm = document.createElement('div');
+      CheckoutProvider.render(EstimateShipping)(estimateShippingForm);
+      esCtx.appendChild(estimateShippingForm);
+    },
+  },
+})($orderSummary),
+```

src/content/docs/dropins/checkout/containers/login-form.mdx

@@ -0,0 +1,59 @@
+---
+title: LoginForm container
+description: Configure the LoginForm container to handle user email input and validation during checkout.
+---
+
+import OptionsTable from '@components/OptionsTable.astro';
+
+The `LoginForm` container is designed to handle user email input and validation within the checkout process.
+
+## LoginForm configurations
+
+The `LoginForm` container provides the following configuration options:
+
+<OptionsTable
+  compact
+  options={[
+    ['Option', 'Type', 'Req?', 'Description'],
+    ['onSignInClick', 'function', 'No', 'A function that handles the sign-in button click. It takes the email (string or null) as an argument.'],
+    ['onSignOutClick', 'function', 'No', 'A function that handles the sign-out button click. It takes no arguments.'],
+  ]}
+/>
+
+## Example
+
+The following example renders the `LoginForm` container on a checkout page, which includes rendering the [`AuthCombine`](/dropins/user-auth/containers/auth-combine/) container from the user auth drop-in component in a modal for authentication:
+
+```ts
+import AuthCombine from '@dropins/storefront-auth/containers/AuthCombine.js';
+import { render as AuthProvider } from '@dropins/storefront-auth/render.js';
+
+import LoginForm from '@dropins/storefront-checkout/containers/LoginForm.js';
+import { render as CheckoutProvider } from '@dropins/storefront-checkout/render.js';
+
+const $login = checkoutFragment.querySelector('.checkout__login');
+
+CheckoutProvider.render(LoginForm, {
+  name: LOGIN_FORM_NAME,
+  onSignInClick: async (initialEmailValue) => {
+    const signInForm = document.createElement('div');
+
+    AuthProvider.render(AuthCombine, {
+      signInFormConfig: {
+        renderSignUpLink: true,
+        initialEmailValue,
+        onSuccessCallback: () => {
+          displayOverlaySpinner();
+        },
+      },
+      signUpFormConfig: {},
+      resetPasswordFormConfig: {},
+    })(signInForm);
+
+    showModal(signInForm);
+  },
+  onSignOutClick: () => {
+    authApi.revokeCustomerToken();
+  },
+})($login),
+```

src/content/docs/dropins/checkout/containers/merged-cart-banner.mdx

@@ -0,0 +1,40 @@
+---
+title: MergedCartBanner container
+description: Configure the MergedCartBanner container to display notifications when items from an old cart are merged into the current cart.
+---
+
+import OptionsTable from '@components/OptionsTable.astro';
+
+The `MergedCartBanner` container is designed to display a notification banner when items from an old cart are merged into the current cart.
+
+When a customer signs in, if they had items in a previous cart, a banner will notify them that the items from their previous cart have been merged with the current cart. You can apply styles to the banner by passing a `className` prop to the container.
+
+## MergedCartBanner configurations
+
+The `MergedCartBanner` container provides the following configuration options:
+
+<OptionsTable
+  compact
+  options={[
+    ['Option', 'Type', 'Req?', 'Description'],
+    ['className', 'string', 'No', 'The CSS class name(s) to apply to the component.'],
+  ]}
+/>
+
+## Example
+
+The following example renders the `MergedCartBanner` container with a custom class name:
+
+```ts
+import MergedCartBanner from '@dropins/storefront-checkout/containers/MergedCartBanner.js';
+import { render as CheckoutProvider } from '@dropins/storefront-checkout/render.js';
+
+const $mergedCartBanner = checkoutFragment.querySelector(
+  '.checkout__merged-cart-banner'
+);
+
+CheckoutProvider.render(MergedCartBanner, {
+  className: 'checkout__merged-cart-banner--custom',
+})($mergedCartBanner);
+```
+`;

src/content/docs/dropins/checkout/containers/order-confirmation-header.mdx

@@ -0,0 +1,39 @@
+---
+title: OrderConfirmationHeader container
+description: Configure the OrderConfirmationHeader container to display order details after a customer places an order.
+---
+
+import OptionsTable from '@components/OptionsTable.astro';
+
+The `OrderConfirmationHeader` container displays the order confirmation page with order details after a customer places an order. It also includes a "Create an account" button for guest users.
+
+## OrderConfirmationHeader configurations
+
+The `OrderConfirmationHeader` container provides the following configuration options:
+
+<OptionsTable
+  compact
+  options={[
+    ['Option', 'Type', 'Req?', 'Description'],
+    ['onSignUpClick', 'Function', 'No', 'The function to call when a customer clicks "Create an account".'],
+    ['orderData', 'Object', 'Yes', 'An object containing the order data, including details such as the email, shipping address, billing address, and order number.'],
+  ]}
+/>
+
+## Example
+
+The following example renders the `OrderConfirmationHeader` container within an order confirmation page. It provides the necessary order data and a handler for the sign-up click event.
+
+```ts
+import OrderConfirmationHeader from '@dropins/storefront-checkout/containers/OrderConfirmationHeader.js';
+import { render as CheckoutProvider } from '@dropins/storefront-checkout/render.js';
+
+const $orderConfirmationHeader = orderConfirmationFragment.querySelector(
+  '.order-confirmation__header'
+);
+
+CheckoutProvider.render(OrderConfirmationHeader, {
+  orderData,
+  onSignUpClick,
+})($orderConfirmationHeader);
+```

src/content/docs/dropins/checkout/containers/out-of-stock.mdx

@@ -0,0 +1,41 @@
+---
+title: OutOfStock container
+description: Configure the OutOfStock container to handle and display out-of-stock items in the cart.
+---
+
+import OptionsTable from '@components/OptionsTable.astro';
+
+The `OutOfStock` container is designed to handle and display items in the shopping cart that are out of stock or have insufficient quantity. You can configure it to handle the removal of out-of-stock items and provide a route to the cart page.
+
+## OutOfStock configurations
+
+The `OutOfStock` container provides the following configuration options:
+
+<OptionsTable
+  compact
+  options={[
+    ['Option', 'Type', 'Req?', 'Description'],
+    ['items', 'CartItem[]', 'Yes', 'The list of items that are out of stock.'],
+    ['onRemoveOutOfStock', 'function', 'No', 'Handles the removal of out-of-stock items. It takes an event as an argument.'],
+    ['routeCart', 'string', 'No', 'The route to the cart page.']
+  ]}
+/>
+
+## Example
+
+The following example renders the `OutOfStock` container to handle and display out-of-stock items in the cart:
+
+```ts
+import * as cartApi from '@dropins/storefront-cart/api.js';
+import OutOfStock from '@dropins/storefront-checkout/containers/OutOfStock.js';
+import { render as CheckoutProvider } from '@dropins/storefront-checkout/render.js';
+
+const $outOfStock = checkoutFragment.querySelector('.checkout__out-of-stock');
+
+CheckoutProvider.render(OutOfStock, {
+  routeCart: () => '/cart',
+  onCartProductsUpdate: (items) => {
+    cartApi.updateProductsFromCart(items).catch(console.error);
+  },
+})($outOfStock),
+```

src/content/docs/dropins/checkout/containers/payment-methods.mdx

@@ -0,0 +1,36 @@
+---
+title: PaymentMethods container
+description: Configure the PaymentMethods container to manage and display available payment methods during checkout.
+---
+
+import OptionsTable from '@components/OptionsTable.astro';
+
+The `PaymentMethods` container is designed to manage and display the available payment methods during the checkout process. You can configure it to handle the selection of payment methods, display the payment method handlers, and manage the main slot for the payment methods.
+
+## PaymentMethods configurations
+
+The `PaymentMethods` container provides the following configuration options:
+
+<OptionsTable
+  compact
+  options={[
+    ['Option', 'Type', 'Req?', 'Description'],
+    ['slots.Main', 'SlotProps<PaymentMethodsMainSlotContext>', 'No', 'The main slot for the payment methods.'],
+    ['slots.Handlers', 'PaymentMethodHandlerSlots', 'No', 'The handlers for different payment methods.']
+  ]}
+/>
+
+## Example
+
+The following example renders the `PaymentMethods` container on a checkout page, displaying the available payment methods in the element with the class `checkout__payment-methods`:
+
+```ts
+import PaymentMethods from '@dropins/storefront-checkout/containers/PaymentMethods.js';
+import { render as CheckoutProvider } from '@dropins/storefront-checkout/render.js';
+
+const $paymentMethods = checkoutFragment.querySelector(
+  '.checkout__payment-methods'
+);
+
+CheckoutProvider.render(PaymentMethods)($paymentMethods),
+```