PAY-6085: Document PayPal Buttons on PDP

src/content/docs/dropins/payment-services/containers/paypal-buttons.mdx

@@ -7,6 +7,7 @@ sidebar:
 
 import TableWrapper from '@components/TableWrapper.astro';
 import Link from '@components/Link.astro';
+import { Aside } from '@astrojs/starlight/components';
 
 The `PayPalButtons` container renders a set of checkout buttons that enable shoppers to pay using <Link href="https://www.paypal.com/" text="PayPal" /> — including PayPal, Venmo, Pay Later, and debit/credit card, depending on which funding sources are enabled for the merchant.
 
@@ -17,6 +18,7 @@ The `PayPalButtons` container provides the following configuration options:
 <TableWrapper nowrap={[0, 1, 2]}>
 | Option | Type | Req? | Description |
 |--------|------|------|-------------|
+| `location` | string | Yes | Location where the PayPal buttons are rendered. Possible values are: `CHECKOUT` and `PRODUCT_DETAIL`. |
 | `onButtonClick` | function | No | Called when the shopper clicks a PayPal button. Receives a `showPaymentSheet` function, which must be called synchronously to begin the PayPal checkout and show the payment sheet. If not provided, clicking the button automatically triggers the payment sheet. |
 | `onSuccess` | function | No | Called when the payment completes successfully. Receives `{ cartId: string }`. If the function returns a promise, it is awaited before marking the payment as successful. If the promise rejects, the payment is marked as failed and the error is passed to `onError` (if provided). |
 | `onError` | function | No | Called when the payment flow fails or is aborted. Receives `{ name: string, message: string }`, containing localized, user-facing error details. These values can be translated using `PaymentServices.PayPalButtons.errors` [language definitions](/dropins/payment-services/dictionary/). |
@@ -38,9 +40,35 @@ The following example demonstrates how to use the `PayPalButtons` container on t
 import PayPalButtons from '@dropins/storefront-payment-services/containers/PayPalButtons.js';
 import { render as PaymentServices } from '@dropins/storefront-payment-services/render.js';
 import * as orderApi from '@dropins/storefront-order/api.js';
+import { PaymentLocation } from '@dropins/storefront-payment-services/api.js';
 
 const $content = document.createElement('div');
 PaymentServices.render(PayPalButtons, {
+  location: PaymentLocation.CHECKOUT,
+  onSuccess: ({ cartId }) => orderApi.placeOrder(cartId),
+  onError: (error) => { console.error(error) },
+})($content);
+```
+
+### Product details page example
+
+The `PayPalButtons` container builds its own shadow cart from the Product Details drop-in's <Link href="https://experienceleague.adobe.com/en/tools/commerce-storefront/dropins/product-details/events/#pdpdata-emits-and-listens" text="pdp/data" /> and <Link href="https://experienceleague.adobe.com/en/tools/commerce-storefront/dropins/product-details/events/#pdpvalues-emits-and-listens" text="pdp/values" /> events on the product details page.
+
+<Aside type="note">
+  The `PayPalButtons` container supports simple, configurable, bundle, virtual, and downloadable products on the product details page.
+</Aside>
+
+The following example demonstrates how to use the `PayPalButtons` container on the product details page.
+
+```js
+import PayPalButtons from '@dropins/storefront-payment-services/containers/PayPalButtons.js';
+import { render as PaymentServices } from '@dropins/storefront-payment-services/render.js';
+import * as orderApi from '@dropins/storefront-order/api.js';
+import { PaymentLocation } from '@dropins/storefront-payment-services/api.js';
+
+const $content = document.createElement('div');
+PaymentServices.render(PayPalButtons, {
+  location: PaymentLocation.PRODUCT_DETAIL,
   onSuccess: ({ cartId }) => orderApi.placeOrder(cartId),
   onError: (error) => { console.error(error) },
 })($content);

src/content/docs/dropins/payment-services/events.mdx

@@ -7,6 +7,7 @@ sidebar:
 ---
 
 import TableWrapper from '@components/TableWrapper.astro';
+import Link from '@components/Link.astro';
 
 The Payment Services drop-in uses the [event bus](/sdk/reference/events) to emit and listen for events, enabling communication between drop-ins and external integrations.
 
@@ -21,8 +22,8 @@ The Payment Services drop-in uses the [event bus](/sdk/reference/events) to emit
 | [checkout/updated](#checkoutupdated-listens) | Listens | Fired by the [Checkout](/dropins/checkout/events/) drop-in when the checkout state is updated. Read by the `GooglePay` container at button click time to determine the selected shipping method and billing address. |
 | [payment-services/initialized/checkout](#payment-servicesinitializedcheckout-emits) | Emits | Emitted when the drop-in finishes initializing for the `CHECKOUT` location. |
 | [payment-services/initialized/product-detail](#payment-servicesinitializedproduct-detail-emits) | Emits | Emitted when the drop-in finishes initializing for the `PRODUCT_DETAIL` location. |
-| [pdp/data](#pdpdata-listens) | Listens | Fired by the [Product Details](https://experienceleague.adobe.com/en/tools/commerce-storefront/dropins/product-details/events/#pdpdata-emits-and-listens) drop-in with product data for the page. Used by the `GooglePay` container on the `PRODUCT_DETAIL` location to build the shadow cart. |
-| [pdp/values](#pdpvalues-listens) | Listens | Fired by the [Product Details](https://experienceleague.adobe.com/en/tools/commerce-storefront/dropins/product-details/events/#pdpvalues-emits-and-listens) drop-in with the shopper's selected product SKU, quantity, and options. Used by the `GooglePay` container on the `PRODUCT_DETAIL` location to build the shadow cart. |
+| [pdp/data](#pdpdata-listens) | Listens | Emitted by the <Link href="https://experienceleague.adobe.com/en/tools/commerce-storefront/dropins/product-details/events/#pdpdata-emits-and-listens" text="Product Details" /> drop-in with product data for the page. The `GooglePay` and `PayPalButtons` containers listen to this event on the `PRODUCT_DETAIL` location to build the shadow cart. |
+| [pdp/values](#pdpvalues-listens) | Listens | Sent by the <Link href="https://experienceleague.adobe.com/en/tools/commerce-storefront/dropins/product-details/events/#pdpvalues-emits-and-listens" text="Product Details" /> drop-in containing the shopper's selected product SKU, quantity, and options. The `GooglePay` and `PayPalButtons` containers use this event on the `PRODUCT_DETAIL` location to build the shadow cart. |
 </TableWrapper>
 
 ## Event details
@@ -137,9 +138,9 @@ See [Payment method availability](/dropins/payment-services/initialization/#paym
 
 ### `pdp/data` (listens)
 
-Fired by the [Product Details](https://experienceleague.adobe.com/en/tools/commerce-storefront/dropins/product-details/events/#pdpdata-emits-and-listens) drop-in with product data for the page. The `GooglePay` container listens to this event, together with [`pdp/values`](#pdpvalues-listens), to build a shadow cart when the shopper clicks the Google Pay button on the `PRODUCT_DETAIL` location.
+Emitted by the <Link href="https://experienceleague.adobe.com/en/tools/commerce-storefront/dropins/product-details/events/#pdpdata-emits-and-listens" text="Product Details" /> drop-in with product data for the page. The `GooglePay` and `PayPalButtons` containers listen to this event, together with [`pdp/values`](#pdpvalues-listens), to build a shadow cart when the shopper clicks a Google Pay or PayPal button on the `PRODUCT_DETAIL` location.
 
-Both events must have been emitted at least once on the event bus before clicking the Google Pay button.
+Both events must have been emitted at least once on the event bus before clicking a Google Pay or PayPal button.
 
 #### Event payload
 
@@ -163,9 +164,9 @@ events.on('pdp/data', (payload) => {
 
 ### `pdp/values` (listens)
 
-Fired by the [Product Details](https://experienceleague.adobe.com/en/tools/commerce-storefront/dropins/product-details/events/#pdpvalues-emits-and-listens) drop-in with the shopper's currently selected product SKU, quantity, and options. The `GooglePay` container listens to this event, together with [`pdp/data`](#pdpdata-listens), to build a shadow cart when the shopper clicks the Google Pay button on the `PRODUCT_DETAIL` location.
+Sent by the <Link href="https://experienceleague.adobe.com/en/tools/commerce-storefront/dropins/product-details/events/#pdpvalues-emits-and-listens" text="Product Details" /> drop-in with the shopper's currently selected product SKU, quantity, and options. The `GooglePay` and `PayPalButtons` containers listen to this event, together with [`pdp/data`](#pdpdata-listens), to build a shadow cart when the shopper clicks a Google Pay or PayPal button on the `PRODUCT_DETAIL` location.
 
-Both events must have been emitted at least once on the event bus before clicking the Google Pay button.
+Both events must have been emitted at least once on the event bus before clicking a Google Pay or PayPal button.
 
 #### Event payload