@snap-pay/elements 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 1.0.0
+
+Initial public release. Nine Elements covering the checkout surface:
+
+- **PaymentElement** — umbrella that auto-picks Wallet + Card based on the session's allowed providers.
+- **WalletElement** — one radio button per mobile-wallet provider (EVC Plus, Sahal, Zaad, eDahab, Jeeb, Premier Wallet).
+- **CardElement** — cross-origin iframe collecting card fields; issues a sandbox token (`tok_sandbox_*`). Live-mode Mastercard tokenization is deferred to a subsequent release.
+- **ExpressCheckoutElement** — one-tap prominent wallet buttons; emits `submit` on click for the merchant's confirm handler.
+- **PaymentMethodSelector** — tabbed switcher between Wallet and Card; lazy-mounts each tab.
+- **BillingAddressElement** — 7-field form; values flow through `confirmPayment` automatically.
+- **CustomerElement** — name / email / phone form.
+- **OtpElement** — configurable-length code input with paste, auto-advance, backspace-back.
+- **QrElement** — placeholder; emits `failed` on mount until the real QR provider handshake ships.
+
+Additional surface:
+- Full Appearance API — spacing, colors, and per-Element rule overrides.
+- Container publishes selection getters (`registerChild`) and form-value getters (`registerValue`) so `confirmPayment` can pick everything up without merchant plumbing.
+- Card element gates live-mode payments at the SDK boundary — merchants using `pk_live_` see a clear error rather than a silent failure.

package/README.md

@@ -0,0 +1,87 @@
+# @snap-pay/elements
+
+Embeddable payment UI components for SNAP checkout. Importing this package registers each Element with `@snap-pay/js`'s factory so `snap.elements(...).create("wallet")` returns an instance.
+
+```bash
+bun add @snap-pay/js @snap-pay/elements
+# or npm/yarn/pnpm
+```
+
+## Usage — Vanilla JS
+
+```ts
+import { Snap } from "@snap-pay/js";
+import "@snap-pay/elements"; // side effect: registers every element
+
+const snap = new Snap("pk_test_…");
+const elements = snap.elements({ clientSecret: sessionId });
+
+// The Payment umbrella auto-picks Wallet vs Card based on the session.
+const payment = elements.create("payment");
+payment.mount("#payment-container");
+
+document.getElementById("pay")!.addEventListener("click", async () => {
+  const result = await snap.confirmPayment({ elements, clientSecret: sessionId });
+  console.log(result.status);
+});
+```
+
+## Available Elements
+
+| Element | Purpose |
+|---|---|
+| `payment` | Umbrella — auto-picks Wallet + Card based on the session's allowed providers |
+| `wallet` | Radio button per mobile-wallet provider (EVC Plus, Zaad, Sahal, eDahab, Jeeb, Premier Wallet) |
+| `card` | Cross-origin iframe collecting card fields, issuing a sandbox token (live-mode tokenization deferred) |
+| `express` | One-tap prominent wallet buttons |
+| `paymentMethodSelector` | Tabbed switcher between Wallet and Card |
+| `billingAddress` | Form: name / address / postal / country. Values flow through `confirmPayment` automatically |
+| `customer` | Form: name / email / phone |
+| `otp` | 6-digit code input with paste + auto-advance |
+| `qr` | Placeholder (real QR handshake not yet shipped — emits `failed` on mount) |
+
+Every Element implements the same imperative surface:
+
+```ts
+element.mount(target);
+element.on("ready" | "change" | "focus" | "blur" | "failed" | "submit", handler);
+element.off(event, handler);
+element.unmount();
+element.destroy();
+```
+
+Form-collecting elements (BillingAddress, Customer, OTP) also expose `element.getValue()` for imperative reads.
+
+## Appearance
+
+```ts
+snap.elements({
+  clientSecret,
+  appearance: {
+    theme: "light", // "light" | "dark" | "auto"
+    primaryColor: "#0066ff",
+    borderRadius: "8px",
+    spacingUnit: "8px",
+    labelColor: "#475569",
+    errorColor: "#dc2626",
+    // Per-Element overrides
+    rules: {
+      card: { border: "2px solid #f00" },
+    },
+  },
+});
+```
+
+## Card iframe URL
+
+The Card Element loads a cross-origin iframe hosted by SNAP. Point at a local dev instance during integration:
+
+```ts
+new Snap("pk_test_…", {
+  cardFrameUrl: "http://localhost:3000/elements/card-frame",
+});
+```
+
+## License
+
+MIT