@openreceive/react 0.3.2 → 0.4.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { CheckoutComponentProps, CheckoutState, QrEncoder, BrowserLoggerOption, CheckoutStatusRefresh, Status, SwapRefundStaging, CheckoutSnapshot, AssetUrlResolver, BrowserLogContext, CheckoutInvoiceSnapshot, ThemePreference, ResolvedTheme, ThemeModel, CheckoutPhase, CheckoutStatusModel, UnixSeconds, BrowserLogger, TransactionDetailsSource } from '@openreceive/browser/headless';
+import { CheckoutComponentProps, CheckoutState, QrEncoder, BrowserLoggerOption, CheckoutStatusRefresh, Status, SwapRefundStaging, CheckoutSnapshot, AssetUrlResolver, ThemePreference, BrowserLogContext, CheckoutInvoiceSnapshot, ResolvedTheme, ThemeModel, CheckoutPhase, CheckoutStatusModel, UnixSeconds, BrowserLogger, TransactionDetailsSource } from '@openreceive/browser/headless';
 export { TransactionDetailsSource, resolveTransactionDetailRows } from '@openreceive/browser/headless';
 
 interface CheckoutData {
@@ -164,11 +164,23 @@ interface CheckoutProps extends CheckoutComponentProps, CheckoutEventHandlers, O
     readonly children?: CheckoutChildren;
     /** Passed through to the payment wizard. See {@link PaymentWizardProps.resolveAssetUrl}. */
     readonly resolveAssetUrl?: AssetUrlResolver;
+    /**
+     * Lock the checkout to one theme. Wins over the stored preference and any
+     * ancestor ThemeScope, and hides the toggle: a host embedding the checkout in
+     * a page that is already dark passes `theme="dark"` and is done. `"system"`
+     * locks to `prefers-color-scheme`, ignoring the stored preference. Unset (the
+     * default), the payer's stored choice applies, falling back to
+     * `defaultTheme`, falling back to the system scheme. The custom element's
+     * `theme` attribute is the same lock.
+     */
+    readonly theme?: ThemePreference;
 }
 interface UseThemeOptions {
     readonly defaultTheme?: ThemePreference;
     readonly storageKey?: string;
     readonly storage?: Storage;
+    /** Lock: this preference wins over storage and scope, and `setTheme` becomes a no-op. */
+    readonly theme?: ThemePreference;
 }
 interface UseThemeResult {
     readonly theme: ThemePreference;
@@ -195,6 +207,8 @@ interface ThemeScopeProps extends Omit<React.HTMLAttributes<HTMLElement>, "child
     readonly defaultTheme?: ThemePreference;
     readonly storageKey?: string;
     readonly storage?: Storage;
+    /** Lock: this preference wins over storage, and the toggle is not rendered. */
+    readonly theme?: ThemePreference;
     readonly themeToggle?: boolean;
     readonly topbarClassName?: string;
     readonly themeToggleClassName?: string;
@@ -225,10 +239,12 @@ interface PaymentWizardProps {
     readonly decodeLinkUrl?: string;
     /**
      * Rewrite a packaged asset path (`assets/provider-icons/strike.png`,
-     * `assets/icons/btc.svg`) into a URL this host can serve. The packaged URLs
-     * only resolve under Vite/Rollup; every other bundler needs this, or the
-     * method icons, provider logos and pay tutorials come out as dead `file://`
-     * links. See docs/guides/provider-registry.md.
+     * `assets/pay_tutorials/strike-1.webp`) into a URL this host can serve. The
+     * packaged URLs only resolve under Vite/Rollup; every other bundler needs
+     * this, or the provider logos and pay tutorials come out as dead `file://`
+     * links. The payment-method icons are compiled in as `data:` URIs and need
+     * nothing; given a resolver they go through it too (`assets/icons/btc.svg`).
+     * See docs/guides/provider-registry.md.
      */
     readonly resolveAssetUrl?: AssetUrlResolver;
     /**

package/dist/index.js

@@ -469,6 +469,7 @@ function useLocalTheme(options = {}) {
   const storageKey = options.storageKey ?? OPENRECEIVE_THEME_STORAGE_KEY;
   const storage = options.storage;
   const defaultTheme = options.defaultTheme;
+  const lockedTheme = options.theme;
   const theme = React4.useSyncExternalStore(
     subscribeStoredTheme,
     React4.useCallback(
@@ -493,9 +494,10 @@ function useLocalTheme(options = {}) {
     getSystemDark,
     getServerSystemDark
   );
-  const themeModel = createThemeModel(theme, { systemDark });
+  const themeModel = createThemeModel(lockedTheme ?? theme, { systemDark });
   const setTheme = React4.useCallback(
     (nextTheme) => {
+      if (lockedTheme !== void 0) return;
       lastSetTheme.set(storageKey, nextTheme);
       writeThemePreference(nextTheme, {
         storage,
@@ -503,13 +505,13 @@ function useLocalTheme(options = {}) {
       });
       notifyStoredThemeChange();
     },
-    [storage, storageKey]
+    [storage, storageKey, lockedTheme]
   );
   const toggleTheme = React4.useCallback(() => {
     setTheme(themeModel.nextTheme);
   }, [setTheme, themeModel.nextTheme]);
   return {
-    theme,
+    theme: lockedTheme ?? theme,
     resolvedTheme: themeModel.resolvedTheme,
     model: themeModel,
     nextTheme: themeModel.nextTheme,
@@ -525,7 +527,7 @@ function useTheme(options = {}) {
   const scoped = React4.useContext(ThemeContext);
   const local = useLocalTheme(options);
   const storageKey = options.storageKey ?? OPENRECEIVE_THEME_STORAGE_KEY;
-  if (scoped !== null && options.storage === void 0 && (options.storageKey === void 0 || options.storageKey === storageKey) && options.defaultTheme === void 0) {
+  if (scoped !== null && options.theme === void 0 && options.storage === void 0 && (options.storageKey === void 0 || options.storageKey === storageKey) && options.defaultTheme === void 0) {
     return { ...scoped, fromScope: true };
   }
   return local;
@@ -568,6 +570,7 @@ function ThemeScope(props) {
     defaultTheme,
     storageKey,
     storage,
+    theme: lockedTheme,
     themeToggle = false,
     topbarClassName,
     themeToggleClassName,
@@ -578,9 +581,11 @@ function ThemeScope(props) {
   const theme = useLocalTheme({
     defaultTheme,
     storageKey,
-    storage
+    storage,
+    theme: lockedTheme
   });
   const scopedChildren = typeof children === "function" ? children(theme) : children;
+  const showsToggle = themeToggle && lockedTheme === void 0;
   return React4.createElement(
     ThemeContext.Provider,
     { value: theme },
@@ -591,7 +596,7 @@ function ThemeScope(props) {
         ...elementProps,
         ...theme.attributes
       },
-      themeToggle ? React4.createElement(
+      showsToggle ? React4.createElement(
         "div",
         {
           className: topbarClassName
@@ -3086,6 +3091,7 @@ function CheckoutView(props) {
     pollIntervalMs,
     paymentWizard = true,
     themeToggle = true,
+    theme: lockedTheme,
     defaultTheme,
     storageKey,
     components,
@@ -3111,9 +3117,11 @@ function CheckoutView(props) {
   });
   const theme = useTheme({
     defaultTheme,
-    storageKey
+    storageKey,
+    theme: lockedTheme
   });
-  const ownsTheme = themeToggle && !theme.fromScope;
+  const stampsTheme = !theme.fromScope;
+  const ownsTheme = themeToggle && !theme.fromScope && lockedTheme === void 0;
   const [swapFocused, setSwapFocused] = React10.useState(false);
   const QRCodeComponent = components?.QRCode ?? QRCode;
   const InvoiceSummaryComponent = components?.InvoiceSummary ?? InvoiceSummary;
@@ -3160,206 +3168,207 @@ function CheckoutView(props) {
       className: joinClassNames(className, orClasses7.root, classNames?.root),
       [OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES3.root]: "",
       // Under ThemeScope, inherit data-theme from the page. Standalone Checkout owns it.
-      ...ownsTheme ? theme.attributes : {}
+      ...stampsTheme ? theme.attributes : {}
     },
-    customChildren === void 0 ? [
-      // Above the amount and OUTSIDE the Lightning pane, which drops out on
-      // the swap deposit panel, on expiry and on the receipt — the payer
-      // needs to know what they are buying on all four screens.
-      checkoutModel.checkout.description === void 0 || checkoutModel.checkout.description === "" ? null : React10.createElement(
-        "p",
-        {
-          key: "order-description",
-          className: joinClassNames(
-            orClasses7.orderDescription,
-            classNames?.orderDescription
-          ),
-          [OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES3.orderDescription]: ""
-        },
-        checkoutModel.checkout.description
-      ),
-      ownsTheme ? React10.createElement(ThemeToggle, {
-        key: "theme",
-        className: classNames?.themeToggle,
-        theme: theme.theme,
-        resolvedTheme: theme.resolvedTheme,
-        onThemeChange: theme.setTheme,
-        ButtonComponent
-      }) : null,
-      mintingLightning ? React10.createElement(
-        "div",
-        {
-          key: "minting-lightning",
-          className: orClasses7.creating
-        },
-        React10.createElement("span", {
-          className: orClasses7.spinner,
-          "aria-hidden": "true"
-        }),
-        React10.createElement("p", null, checkoutLabels6.preparingPayment)
-      ) : null,
-      hideLightning ? null : React10.createElement(
-        "div",
-        {
-          key: "payment-layout",
-          className: expired || settled ? orClasses7.paymentLayoutExpired : orClasses7.paymentLayout
-        },
-        lightningPane,
-        React10.createElement(
+    [
+      // Order context from the host, composed ABOVE the shipped payment UI —
+      // the same position as the custom element's `order` slot. Children never
+      // replace the payment UI; a host that wants its own checkout builds on
+      // useCheckout / @openreceive/browser/headless instead.
+      customChildren === void 0 ? null : React10.createElement(React10.Fragment, { key: "order-children" }, customChildren),
+      ...[
+        // Above the amount and OUTSIDE the Lightning pane, which drops out on
+        // the swap deposit panel, on expiry and on the receipt — the payer
+        // needs to know what they are buying on all four screens.
+        checkoutModel.checkout.description === void 0 || checkoutModel.checkout.description === "" ? null : React10.createElement(
+          "p",
+          {
+            key: "order-description",
+            className: joinClassNames(orClasses7.orderDescription, classNames?.orderDescription),
+            [OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES3.orderDescription]: ""
+          },
+          checkoutModel.checkout.description
+        ),
+        ownsTheme ? React10.createElement(ThemeToggle, {
+          key: "theme",
+          className: classNames?.themeToggle,
+          theme: theme.theme,
+          resolvedTheme: theme.resolvedTheme,
+          onThemeChange: theme.setTheme,
+          ButtonComponent
+        }) : null,
+        mintingLightning ? React10.createElement(
           "div",
           {
-            key: "payment-info",
-            className: orClasses7.paymentInfo
+            key: "minting-lightning",
+            className: orClasses7.creating
           },
-          expired || settled ? null : React10.createElement(
-            "p",
-            {
-              key: "invoice-title",
-              className: joinClassNames(
-                orClasses7.invoiceTitle,
-                classNames?.invoiceTitle
-              )
-            },
-            checkoutLabels6.bitcoinLightningInvoice
-          ),
-          React10.createElement(WaitingState, {
-            key: "waiting",
-            waiting: checkoutModel.waiting,
-            statusTitle: checkoutModel.statusTitle,
-            statusDetail: checkoutModel.statusDetail,
-            settled,
-            className: classNames?.waiting
+          React10.createElement("span", {
+            className: orClasses7.spinner,
+            "aria-hidden": "true"
           }),
-          checkoutModel.countdownLabel === void 0 ? null : React10.createElement(
-            "div",
-            {
-              key: "countdown",
-              className: joinClassNames(orClasses7.countdown, classNames?.countdown)
-            },
-            checkoutModel.countdownPrefix,
-            " ",
-            React10.createElement(
-              "strong",
-              { className: orClasses7.countdownStrong },
-              checkoutModel.countdownLabel
-            )
-          ),
-          showSummaryMeta ? React10.createElement(InvoiceSummaryComponent, {
-            key: "summary",
-            status: checkoutModel.status,
-            PaymentStateComponent,
-            className: classNames?.summary,
-            classNames
-          }) : null,
-          settled ? React10.createElement(TransactionDetails, {
-            key: "transaction-details",
-            // The model IS the checkout state, so the panel reads
-            // the same derivation the rest of the screen does. It
-            // used to re-flatten the snapshot separately, which
-            // reported the displayed ATTEMPT's transaction /
-            // workflow state on a checkout the state already knows
-            // is paid.
-            //
-            // The SAME panel the swap flow renders one screen
-            // earlier. A payer's whole evidence that they paid is a
-            // payment hash and, on a swap, a deposit txid — so the
-            // most keep-worthy screen gets copy buttons and
-            // explorer links, not un-copyable text. No
-            // `decodeLinkUrl` is passed, so the bolt11 never
-            // reaches a third party.
-            state: checkoutModel,
-            className: classNames?.details,
-            onError
-          }) : expired ? React10.createElement(
+          React10.createElement("p", null, checkoutLabels6.preparingPayment)
+        ) : null,
+        hideLightning ? null : React10.createElement(
+          "div",
+          {
+            key: "payment-layout",
+            className: expired || settled ? orClasses7.paymentLayoutExpired : orClasses7.paymentLayout
+          },
+          lightningPane,
+          React10.createElement(
             "div",
             {
-              key: "expired-actions",
-              className: joinClassNames(orClasses7.actions, classNames?.actions),
-              [OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES3.actions]: ""
+              key: "payment-info",
+              className: orClasses7.paymentInfo
             },
-            React10.createElement(
-              ButtonComponent ?? "button",
+            expired || settled ? null : React10.createElement(
+              "p",
               {
-                type: "button",
-                className: orClasses7.btn,
-                onClick: startOver
+                key: "invoice-title",
+                className: joinClassNames(orClasses7.invoiceTitle, classNames?.invoiceTitle)
               },
-              checkoutLabels6.startOver
-            )
-          ) : React10.createElement(
-            "div",
-            {
-              key: "actions",
-              className: joinClassNames(orClasses7.actions, classNames?.actions),
-              [OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES3.actions]: ""
-            },
-            React10.createElement(CopyButton, {
-              key: "copy-invoice",
-              invoice: checkoutModel.invoice,
-              copyInvoice: checkoutModel.copyInvoice,
-              onError,
-              logger,
-              ButtonComponent,
-              className: classNames?.copyButton
-            }),
-            // Opt-in slot: the default checkout ships no wallet button, so a
-            // desktop payer is never sent to a handler that does not exist.
-            OpenWalletButtonComponent === void 0 ? null : React10.createElement(OpenWalletButtonComponent, {
-              key: "open-wallet",
-              invoice: checkoutModel.invoice,
-              openWallet: checkoutModel.openWallet,
-              onError,
-              logger,
-              ButtonComponent,
-              className: classNames?.openWalletButton
+              checkoutLabels6.bitcoinLightningInvoice
+            ),
+            React10.createElement(WaitingState, {
+              key: "waiting",
+              waiting: checkoutModel.waiting,
+              statusTitle: checkoutModel.statusTitle,
+              statusDetail: checkoutModel.statusDetail,
+              settled,
+              className: classNames?.waiting
             }),
-            decodeInvoiceHref === void 0 ? null : React10.createElement(
-              "a",
+            checkoutModel.countdownLabel === void 0 ? null : React10.createElement(
+              "div",
+              {
+                key: "countdown",
+                className: joinClassNames(orClasses7.countdown, classNames?.countdown)
+              },
+              checkoutModel.countdownPrefix,
+              " ",
+              React10.createElement(
+                "strong",
+                { className: orClasses7.countdownStrong },
+                checkoutModel.countdownLabel
+              )
+            ),
+            showSummaryMeta ? React10.createElement(InvoiceSummaryComponent, {
+              key: "summary",
+              status: checkoutModel.status,
+              PaymentStateComponent,
+              className: classNames?.summary,
+              classNames
+            }) : null,
+            settled ? React10.createElement(TransactionDetails, {
+              key: "transaction-details",
+              // The model IS the checkout state, so the panel reads
+              // the same derivation the rest of the screen does. It
+              // used to re-flatten the snapshot separately, which
+              // reported the displayed ATTEMPT's transaction /
+              // workflow state on a checkout the state already knows
+              // is paid.
+              //
+              // The SAME panel the swap flow renders one screen
+              // earlier. A payer's whole evidence that they paid is a
+              // payment hash and, on a swap, a deposit txid — so the
+              // most keep-worthy screen gets copy buttons and
+              // explorer links, not un-copyable text. No
+              // `decodeLinkUrl` is passed, so the bolt11 never
+              // reaches a third party.
+              state: checkoutModel,
+              className: classNames?.details,
+              onError
+            }) : expired ? React10.createElement(
+              "div",
               {
-                key: "decode-invoice",
-                className: orClasses7.btn,
-                href: decodeInvoiceHref,
-                rel: "noreferrer",
-                target: "_blank"
+                key: "expired-actions",
+                className: joinClassNames(orClasses7.actions, classNames?.actions),
+                [OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES3.actions]: ""
               },
-              checkoutLabels6.decodeInvoice
+              React10.createElement(
+                ButtonComponent ?? "button",
+                {
+                  type: "button",
+                  className: orClasses7.btn,
+                  onClick: startOver
+                },
+                checkoutLabels6.startOver
+              )
+            ) : React10.createElement(
+              "div",
+              {
+                key: "actions",
+                className: joinClassNames(orClasses7.actions, classNames?.actions),
+                [OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES3.actions]: ""
+              },
+              React10.createElement(CopyButton, {
+                key: "copy-invoice",
+                invoice: checkoutModel.invoice,
+                copyInvoice: checkoutModel.copyInvoice,
+                onError,
+                logger,
+                ButtonComponent,
+                className: classNames?.copyButton
+              }),
+              // Opt-in slot: the default checkout ships no wallet button, so a
+              // desktop payer is never sent to a handler that does not exist.
+              OpenWalletButtonComponent === void 0 ? null : React10.createElement(OpenWalletButtonComponent, {
+                key: "open-wallet",
+                invoice: checkoutModel.invoice,
+                openWallet: checkoutModel.openWallet,
+                onError,
+                logger,
+                ButtonComponent,
+                className: classNames?.openWalletButton
+              }),
+              decodeInvoiceHref === void 0 ? null : React10.createElement(
+                "a",
+                {
+                  key: "decode-invoice",
+                  className: orClasses7.btn,
+                  href: decodeInvoiceHref,
+                  rel: "noreferrer",
+                  target: "_blank"
+                },
+                checkoutLabels6.decodeInvoice
+              )
             )
           )
-        )
-      ),
-      paymentWizard && !settled && (!expired || swapFocused) ? React10.createElement(PaymentWizard, {
-        key: "wizard",
-        // Only pass invoice when it's a real bolt11 (non-empty, non-deferred).
-        invoice: checkoutModel.invoice || void 0,
-        checkout: checkoutModel.checkout,
-        className: classNames?.wizard,
-        logger,
-        onError,
-        onSwapFocusChange: setSwapFocused,
-        prefix,
-        qrEncoder,
-        decodeLinkUrl,
-        logContext: getCheckoutLogContext({
-          invoice_id: checkoutModel.invoice_id,
-          payment_hash: checkoutModel.payment_hash,
-          amount_msats: checkoutModel.amount_msats
-        }),
-        onProviderCopy,
-        onCopy,
-        onRequestLightning,
-        onSwapStarted,
-        resolveAssetUrl,
-        assetBaseUrl,
-        // Whether a payer who closes the tab has a URL to come back
-        // to. Explicit wins — only the host knows about a per-order
-        // route of its own; otherwise infer it from the two props that
-        // put the reference in the URL.
-        resumable: resumable ?? (syncUrl === true || routeReference !== void 0),
-        // The engine's staged refund address rides the controller this
-        // model owns, so a poll cannot wipe a review in progress.
-        swapRefund: checkoutModel
-      }) : null
-    ] : customChildren
+        ),
+        paymentWizard && !settled && (!expired || swapFocused) ? React10.createElement(PaymentWizard, {
+          key: "wizard",
+          // Only pass invoice when it's a real bolt11 (non-empty, non-deferred).
+          invoice: checkoutModel.invoice || void 0,
+          checkout: checkoutModel.checkout,
+          className: classNames?.wizard,
+          logger,
+          onError,
+          onSwapFocusChange: setSwapFocused,
+          prefix,
+          qrEncoder,
+          decodeLinkUrl,
+          logContext: getCheckoutLogContext({
+            invoice_id: checkoutModel.invoice_id,
+            payment_hash: checkoutModel.payment_hash,
+            amount_msats: checkoutModel.amount_msats
+          }),
+          onProviderCopy,
+          onCopy,
+          onRequestLightning,
+          onSwapStarted,
+          resolveAssetUrl,
+          assetBaseUrl,
+          // Whether a payer who closes the tab has a URL to come back
+          // to. Explicit wins — only the host knows about a per-order
+          // route of its own; otherwise infer it from the two props that
+          // put the reference in the URL.
+          resumable: resumable ?? (syncUrl === true || routeReference !== void 0),
+          // The engine's staged refund address rides the controller this
+          // model owns, so a poll cannot wipe a review in progress.
+          swapRefund: checkoutModel
+        }) : null
+      ]
+    ]
   );
 }