@htmlbricks/hb-payment-paypal 0.71.35 → 0.71.37

package/README.md

@@ -1,39 +1,130 @@
-## `hb-payment-paypal` — payment PayPal
+# `hb-payment-paypal` — integrator guide
 
-**Category:** commerce  
-**Tags:** commerce, payment
+**Category:** commerce · **Tags:** commerce, payment · **Package:** `@htmlbricks/hb-payment-paypal`
 
-### What it does
+## Summary
 
-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 tag
 
-### Attributes (snake_case; use string values in HTML)
+```html
+<hb-payment-paypal …></hb-payment-paypal>
+```
+
+## Attributes (HTML / reflected props)
+
+All names are **snake_case**. Values from HTML are **strings**; **`total`** is coerced with **`Number(...)`** inside the component.
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `paypalid` | Yes | PayPal **client id** (passed to the SDK as **`client-id`**). |
+| `currency` | No | **`EUR`** or **`USD`** (uppercased when set; defaults to **`EUR`**). |
+| `total` | No | Order amount (string or number after coercion; default **`0`** in the implementation). |
+| `id` | No | Optional host id. |
+| `style` | No | Optional on **`Component`**; normal host **`style`** still applies in the light DOM. |
+
+## 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
+
+The shadow tree forwards Bulma theme setup on `:host`. PayPal’s iframe still controls the inner button pixels.
 
-- `id`, `style` (optional): strings.
-- `paypalid` (required): string — PayPal client / app id.
-- `currency` (required): `"EUR"` | `"USD"` (string).
-- `total` (required): number as string — order amount.
+**CSS custom properties** (documented in `extra/docs.ts`):
 
-### Events
+| 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`). |
 
-- `paymentCompleted`: `{ method: "paypal"; total: number }`.
+See [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/) for how to set `--bulma-*` on ancestors.
 
-### Usage notes
+**CSS part**
 
-- **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.
+| 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. |
 
-### Styling (Bulma)
+## TypeScript typings (authoring)
 
-**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.
+From `types/webcomponent.type.d.ts`: **`Component`** (`paypalid`, optional **`currency`**, **`total`**, **`id`**, **`style`**) and **`Events`** (`paymentCompleted`).
 
-### Minimal HTML example
+## Integration notes
+
+- **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>
+```
+
+### With completion handler
 
 ```html
-<hb-payment-paypal paypalid="YOUR_CLIENT_ID" currency="EUR" total="40"></hb-payment-paypal>
+<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

@@ -60,9 +60,7 @@
             }
           },
           "required": [
-            "paypalid",
-            "currency",
-            "total"
+            "paypalid"
           ],
           "type": "object"
         }
@@ -87,23 +85,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 +184,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-payment-paypal",
-  "version": "0.71.35"
+  "version": "0.71.37"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-payment-paypal",
-  "version": "0.71.35",
+  "version": "0.71.37",
   "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": [

package/types/webcomponent.type.d.json

@@ -26,9 +26,7 @@
         }
       },
       "required": [
-        "paypalid",
-        "currency",
-        "total"
+        "paypalid"
       ],
       "type": "object"
     }

package/types/webcomponent.type.d.ts

@@ -1,11 +1,11 @@
 export type Component = {
-	id?: string;
-	style?: string;
-	paypalid: string;
-	currency: "EUR" | "USD";
-	total: number;
+  id?: string;
+  style?: string;
+  paypalid: string;
+  currency?: "EUR" | "USD";
+  total?: number;
 };
 
 export type Events = {
-	paymentCompleted: { method: "paypal"; total: number };
+  paymentCompleted: { method: "paypal"; total: number };
 };