@htmlbricks/hb-payment-paypal 0.71.34 → 0.71.36

package/README.md

@@ -1,39 +1,127 @@
-## `hb-payment-paypal` — payment PayPal
+# hb-payment-paypal
 
-**Category:** commerce  
-**Tags:** commerce, payment
+**Category:** commerce · **Tags:** commerce, payment · **Package:** `@htmlbricks/hb-payment-paypal`
 
-### What it does
+## Overview
 
-Loads the PayPal JS SDK with your client id and currency, renders PayPal Buttons for a fixed order total, captures payment on approval, and dispatches `paymentCompleted` when the order is captured successfully.
+`hb-payment-paypal` loads the official [PayPal JS SDK](https://developer.paypal.com/docs/checkout/) using your **client id** and **currency**, renders **PayPal Buttons** for a **single fixed order total**, and on buyer approval runs **order capture** (`intent: "CAPTURE"`). When capture succeeds, the element dispatches a **`paymentCompleted`** custom event so your host page can continue checkout, clear a cart, or show a receipt.
 
-### Custom element
+The visible PayPal button chrome is drawn by PayPal inside the mounted region; this web component owns wiring, totals, and the completion event.
 
-`hb-payment-paypal`
+## Custom element
 
-### Attributes (snake_case; use string values in HTML)
+```text
+hb-payment-paypal
+```
+
+## Attributes (HTML)
+
+All attribute names are **snake_case**. Values from HTML are **strings**; the component coerces `total` to a number when needed.
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `paypalid` | Yes | PayPal **client id** (REST app / “Client ID” in the PayPal Developer Dashboard). Passed to the SDK as `client-id`. |
+| `currency` | Yes | Order currency: **`EUR`** or **`USD`**. Non-empty values are normalized to **uppercase**; if missing, the implementation defaults to **`EUR`**. |
+| `total` | Yes | Order **amount** as a string (e.g. `"40"`, `"12.5"`). Coerced with `Number(...)` for PayPal’s `purchase_units[].amount.value`. Use a decimal string that matches your pricing rules. |
+| `id` | No | Optional string (default empty). Reserved for host/DOM use; does not change PayPal SDK behavior in the current markup. |
+
+> **Typings note:** `types/webcomponent.type.d.ts` may list an optional `style` field on the logical `Component` shape. The current Svelte implementation does not read `style` from props, so setting a `style` attribute has no defined effect on this build.
+
+## Behavior
+
+1. **Script load:** On mount and when `paypalid` / `currency` / `total` change, the component calls `loadScript` from `@paypal/paypal-js` with `client-id` and `currency`.
+2. **Buttons:** Renders PayPal Buttons with `layout: "horizontal"`, `tagline: false`, `height: 40`.
+3. **Order creation:** `createOrder` builds one purchase unit with `intent: "CAPTURE"` and `amount` `{ currency_code, value: String(total) }`.
+4. **Approval:** `onApprove` calls `actions.order.capture()`. On success it dispatches **`paymentCompleted`** with `{ method: "paypal", total }` where `total` is the **numeric** prop value used for the order (not necessarily re-read from PayPal’s response).
+5. **Teardown:** On component destroy, it attempts `paypal.Buttons?.().close?.()` to release the button instance.
+6. **Errors:** SDK load or render failures are logged with `console.error`; they do not emit a dedicated custom event in the current implementation.
+
+Changing **`paypalid`**, **`currency`**, or **`total`** after load can trigger a remount path (existing buttons are closed before a new load). Ensure your host state stays in sync with the amount shown to the buyer.
+
+## Events
+
+Listen with `addEventListener` or framework bindings on the custom element.
+
+| Event | `detail` |
+|-------|----------|
+| `paymentCompleted` | `{ method: "paypal"; total: number }` |
+
+Use this event as the signal that **capture completed on the client**; still verify the transaction on your **server** (webhooks or REST) before fulfilling goods or services.
+
+## Styling
 
-- `id`, `style` (optional): strings.
-- `paypalid` (required): string — PayPal client / app id.
-- `currency` (required): `"EUR"` | `"USD"` (string).
-- `total` (required): number as string — order amount.
+The shadow tree forwards Bulma theme setup on `:host`. PayPal’s iframe still controls the inner button pixels.
 
-### Events
+**CSS custom properties** (documented in `extra/docs.ts`):
 
-- `paymentCompleted`: `{ method: "paypal"; total: number }`.
+| Variable | Role |
+|----------|------|
+| `--bulma-background` | Surface behind the PayPal mount region. |
+| `--bulma-text` | Inline copy or labels beside the SDK (if any). |
+| `--bulma-border` | Dividers next to sibling checkout panels. |
+| `--bulma-radius` | Corner radius for Bulma-framed wrappers. |
+| `--hb-checkout-border` | Legacy divider token for composite checkout layouts (defaults to `--bulma-border`). |
 
-### Usage notes
+See [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/) for how to set `--bulma-*` on ancestors.
 
-- **CSS variables:** `--hb-checkout-border`, Bulma `--bulma-*` (see `extra/docs.ts`).
-- **CSS parts:** `btn` (PayPal button surface).
-- Ensure CSP and PayPal script loading match your host app; totals are fixed for the rendered session.
+**CSS part**
 
-### Styling (Bulma)
+| Part | Target |
+|------|--------|
+| `btn` | Host wrapper around the PayPal Buttons mount (`#paypalbtn`). Use `::part(btn)` for **layout and spacing** around the SDK; do not expect to theme PayPal’s internal button art. |
 
-**Bulma** theme tokens are applied on `:host` only; the PayPal SDK injects its own button UI into `#paypalbtn`. Use **`--bulma-*`** for consistency with sibling checkout components.
+## Integration notes
 
-### Minimal HTML example
+- **Content Security Policy:** Allow PayPal’s script and frame origins required by the JS SDK and Smart Payment Buttons, or the load/render step will fail.
+- **Sandbox vs live:** Use a **sandbox client id** during development and your **live client id** in production; totals and currency must match what you persist for the order.
+- **Currencies:** Only **EUR** and **USD** are handled in the type layer; other codes are not part of the declared `Component` contract.
+- **Card UI:** Older commented markup in `component.wc.svelte` referenced an `hb-form` card flow; that path is **not** active in the shipped template. This component is **PayPal-button only** today.
+
+## Examples
+
+### Minimal markup
 
 ```html
-<hb-payment-paypal paypalid="YOUR_CLIENT_ID" currency="EUR" total="40"></hb-payment-paypal>
+<hb-payment-paypal
+  paypalid="YOUR_CLIENT_ID"
+  currency="EUR"
+  total="40"
+></hb-payment-paypal>
+```
+
+### With completion handler
+
+```html
+<hb-payment-paypal
+  id="checkout-paypal"
+  paypalid="YOUR_CLIENT_ID"
+  currency="USD"
+  total="12.50"
+></hb-payment-paypal>
+
+<script>
+  const el = document.getElementById("checkout-paypal");
+  el.addEventListener("paymentCompleted", (e) => {
+    const { method, total } = e.detail;
+    console.log("Captured", method, total);
+  });
+</script>
 ```
+
+### Fractional totals
+
+```html
+<hb-payment-paypal
+  paypalid="YOUR_CLIENT_ID"
+  currency="EUR"
+  total="1499.99"
+></hb-payment-paypal>
+```
+
+## Related files
+
+| File | Purpose |
+|------|---------|
+| `component.wc.svelte` | PayPal SDK load, buttons, capture, event dispatch. |
+| `types/webcomponent.type.d.ts` | `Component` and `Events` typings for authors and generated declarations. |
+| `extra/docs.ts` | Catalog metadata, `styleSetup` (vars / parts), Storybook args, examples. |

package/manifest.json

@@ -87,23 +87,41 @@
   },
   "styleSetup": {
     "vars": [
+      {
+        "name": "--bulma-background",
+        "valueType": "color",
+        "defaultValue": "#ffffff",
+        "description": "Host surface behind the PayPal mount region."
+      },
+      {
+        "name": "--bulma-text",
+        "valueType": "color",
+        "defaultValue": "#363636",
+        "description": "Any inline copy or labels rendered beside the SDK mount."
+      },
       {
         "name": "--bulma-border",
         "valueType": "color",
         "defaultValue": "#dbdbdb",
-        "description": "Optional separators if extended beside the PayPal mount point."
+        "description": "Dividers when the block sits next to other checkout panels."
+      },
+      {
+        "name": "--bulma-radius",
+        "valueType": "number",
+        "defaultValue": "0.375rem",
+        "description": "Corner radius for any Bulma-framed wrapper around the mount."
       },
       {
         "name": "--hb-checkout-border",
         "valueType": "color",
-        "defaultValue": "",
-        "description": "Legacy divider variable used by parent checkout layouts."
+        "defaultValue": "var(--bulma-border)",
+        "description": "Legacy divider token for parent checkout layouts (falls back to Bulma border)."
       }
     ],
     "parts": [
       {
         "name": "btn",
-        "description": "paypal button css"
+        "description": "Host wrapper around the PayPal Buttons mount target (`#paypalbtn`)."
       }
     ]
   },
@@ -168,5 +186,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-payment-paypal",
-  "version": "0.71.34"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-payment-paypal",
-  "version": "0.71.34",
+  "version": "0.71.36",
   "contributors": [],
   "description": "Loads the PayPal JS SDK with your client id and currency, renders PayPal Buttons for a fixed order total, captures payment on approval, and dispatches paymentCompleted when the order is captured successfully.",
   "licenses": [