@cartridge/controller 0.11.2 → 0.11.3

package/src/toast/index.ts

@@ -0,0 +1,263 @@
+import { ToastOptions } from "./types";
+import {
+  isInIframe,
+  getTargetDocument,
+  getToastContainer,
+  DEFAULT_DURATION,
+  DEFAULT_POSITION,
+  TOAST_MESSAGE_TYPE,
+  removeToast,
+} from "./utils";
+import { injectStyles } from "./styles";
+import {
+  injectErrorStyles,
+  createErrorToast,
+  injectTransactionStyles,
+  createTransactionToast,
+  injectNetworkSwitchStyles,
+  createNetworkSwitchToast,
+  injectAchievementStyles,
+  createAchievementToast,
+  injectQuestStyles,
+  createQuestToast,
+  injectMarketplaceStyles,
+  createMarketplaceToast,
+} from "./variants";
+import { addProgressBarToToast } from "./utils/progress-bar";
+
+// Create toast element based on variant
+function createToastElement(options: ToastOptions): HTMLElement {
+  switch (options.variant) {
+    case "error":
+      return createErrorToast(options);
+    case "transaction":
+      return createTransactionToast(options);
+    case "network-switch":
+      return createNetworkSwitchToast(options);
+    case "achievement":
+      return createAchievementToast(options);
+    case "quest":
+      return createQuestToast(options);
+    case "marketplace":
+      return createMarketplaceToast(options);
+  }
+}
+
+// Inject variant-specific styles
+function injectVariantStyles(
+  targetDoc: Document,
+  variant: ToastOptions["variant"],
+): void {
+  switch (variant) {
+    case "error":
+      injectErrorStyles(targetDoc);
+      break;
+    case "transaction":
+      injectTransactionStyles(targetDoc);
+      break;
+    case "network-switch":
+      injectNetworkSwitchStyles(targetDoc);
+      break;
+    case "achievement":
+      injectAchievementStyles(targetDoc);
+      break;
+    case "quest":
+      injectQuestStyles(targetDoc);
+      break;
+    case "marketplace":
+      injectMarketplaceStyles(targetDoc);
+      break;
+  }
+}
+
+// Show toast on target document (parent or current)
+function showToastOnDocument(
+  targetDoc: Document,
+  options: ToastOptions,
+): () => void {
+  // Inject common styles if needed
+  injectStyles(targetDoc);
+
+  // Inject variant-specific styles
+  injectVariantStyles(targetDoc, options.variant);
+
+  // Get container
+  const position = options.position || DEFAULT_POSITION;
+  const container = getToastContainer(targetDoc, position);
+
+  // Create toast element
+  const toastElement = createToastElement(options);
+
+  // Set up dismiss function
+  const dismiss = () => removeToast(toastElement);
+
+  // Add to container
+  container.appendChild(toastElement);
+
+  // Setup close button
+  const closeButton = toastElement.querySelector("#close-button");
+  if (closeButton) {
+    closeButton.addEventListener("click", dismiss);
+  }
+
+  // Handle duration and progress bar
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+  const duration = options.duration ?? DEFAULT_DURATION;
+  const isInfiniteDuration = !isFinite(duration) || duration <= 0;
+
+  // Add progress bar to all variants except network-switch
+  if (options.variant !== "network-switch") {
+    // Determine border radius based on variant
+    const borderRadius =
+      options.variant === "error" || options.variant === "transaction" ? 8 : 4;
+
+    if (isInfiniteDuration) {
+      // Show static progress bar for infinite duration (no animation, no auto-dismiss)
+      addProgressBarToToast(toastElement, Infinity, () => {}, borderRadius);
+    } else {
+      // Animated progress bar with auto-dismiss
+      addProgressBarToToast(toastElement, duration, dismiss, borderRadius);
+    }
+  } else if (!isInfiniteDuration) {
+    // Network-switch variant uses setTimeout instead of progress bar
+    timeoutId = setTimeout(dismiss, duration);
+  }
+
+  // Return dismiss function
+  return () => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+    dismiss();
+  };
+}
+
+// Set up message listener on parent window to handle toast requests from iframes
+let messageListenerSetup = false;
+function setupMessageListener(): void {
+  if (messageListenerSetup || typeof window === "undefined") {
+    return;
+  }
+
+  // Only set up listener on parent window (not in iframe)
+  if (isInIframe()) {
+    return;
+  }
+
+  window.addEventListener("message", (event) => {
+    // Basic origin check - in production, you might want stricter checks
+    if (event.data?.type === TOAST_MESSAGE_TYPE && event.data?.options) {
+      const targetDoc = document;
+      if (targetDoc) {
+        showToastOnDocument(targetDoc, event.data.options);
+      }
+    }
+  });
+
+  messageListenerSetup = true;
+}
+
+/**
+ * Show a toast notification
+ *
+ * The toast will always appear on the parent page, even if called from within an iframe.
+ * This ensures toasts are visible above all content, including the keychain iframe.
+ *
+ * @param options - Toast options with variant-specific properties
+ * @returns A function to manually dismiss the toast
+ *
+ * @example
+ * ```ts
+ * import { toast } from "@cartridge/controller";
+ *
+ * // Error toast
+ * toast({
+ *   variant: "error",
+ *   message: "Transaction failed",
+ * });
+ *
+ * // Transaction toast
+ * toast({
+ *   variant: "transaction",
+ *   hash: "0x1234...",
+ *   status: "success",
+ *   amount: "100",
+ *   token: "ETH"
+ * });
+ *
+ * // Network switch toast
+ * toast({
+ *   variant: "network-switch",
+ *   networkName: "Mainnet",
+ *   networkIcon: <url to icon image>
+ * });
+ *
+ * // Achievement toast
+ * toast({
+ *   variant: "achievement",
+ *   itemName: "First Achievement",
+ *   itemImage: "https://example.com/trophy.png"
+ *   action: "purchased" | "sold",
+ * });
+ *
+ * // Marketplace toast
+ * toast({
+ *   variant: "marketplace",
+ *   itemName: "Cool NFT #123",
+ *   action: "purchased",
+ *   price: "0.5",
+ *   currency: "ETH",
+ *   image: "https://example.com/nft.png"
+ * });
+ * ```
+ */
+export function toast(options: ToastOptions): () => void {
+  // Ensure we're in a browser environment
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    console.warn("Toast can only be used in a browser environment");
+    return () => {};
+  }
+
+  // Set up message listener on parent window if not already set up
+  setupMessageListener();
+
+  // Check if we're in an iframe
+  if (isInIframe()) {
+    // Try to get parent document
+    const targetDoc = getTargetDocument();
+
+    if (targetDoc) {
+      // Same-origin iframe, can access parent document directly
+      return showToastOnDocument(targetDoc, options);
+    } else {
+      // Cross-origin iframe, use postMessage
+      try {
+        if (window.parent) {
+          window.parent.postMessage(
+            {
+              type: TOAST_MESSAGE_TYPE,
+              options: options,
+            },
+            "*", // In production, specify target origin
+          );
+        }
+      } catch (e) {
+        console.warn("Failed to send toast message to parent:", e);
+      }
+
+      // Return a no-op dismiss function for cross-origin case
+      return () => {};
+    }
+  } else {
+    // Not in iframe, show toast directly on current document
+    const targetDoc = document;
+    return showToastOnDocument(targetDoc, options);
+  }
+}
+
+export * from "./types";
+
+// Initialize message listener when module loads (if in browser environment)
+if (typeof window !== "undefined") {
+  setupMessageListener();
+}

package/src/toast/styles.ts

@@ -0,0 +1,142 @@
+import { TOAST_CONTAINER_ID } from "./utils";
+
+// Inject CSS styles if not already present
+export function injectStyles(targetDoc: Document): void {
+  if (targetDoc.getElementById("cartridge-toast-styles")) {
+    return;
+  }
+
+  const style = targetDoc.createElement("style");
+  style.id = "cartridge-toast-styles";
+  style.textContent = getCommonStyles();
+  targetDoc.head.appendChild(style);
+}
+
+function getCommonStyles(): string {
+  return `
+    #${TOAST_CONTAINER_ID} {
+      position: fixed;
+      z-index: 999999;
+      pointer-events: none;
+      display: flex;
+      flex-direction: column;
+      align-items: flex-end;
+      gap: 12px;
+    }
+
+    #${TOAST_CONTAINER_ID}.top-left {
+      top: 20px;
+      left: 20px;
+      align-items: flex-start;
+    }
+
+    #${TOAST_CONTAINER_ID}.top-right {
+      top: 20px;
+      right: 20px;
+      align-items: flex-end;
+    }
+
+    #${TOAST_CONTAINER_ID}.top-center {
+      top: 20px;
+      left: 50%;
+      transform: translateX(-50%);
+      align-items: center;
+    }
+
+    #${TOAST_CONTAINER_ID}.bottom-left {
+      bottom: 20px;
+      left: 20px;
+      align-items: flex-start;
+    }
+
+    #${TOAST_CONTAINER_ID}.bottom-right {
+      bottom: 20px;
+      right: 20px;
+      align-items: flex-end;
+    }
+
+    #${TOAST_CONTAINER_ID}.bottom-center {
+      bottom: 20px;
+      left: 50%;
+      transform: translateX(-50%);
+      align-items: center;
+    }
+
+    .cartridge-toast {
+      box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
+      display: flex;
+      align-items: center;
+      animation: cartridge-toast-slide-in 0.3s ease-out;
+      overflow: hidden;
+      pointer-events: auto;
+    }
+
+    #${TOAST_CONTAINER_ID}.top-right .cartridge-toast,
+    #${TOAST_CONTAINER_ID}.bottom-right .cartridge-toast {
+      align-self: flex-end;
+    }
+
+    #${TOAST_CONTAINER_ID}.top-left .cartridge-toast,
+    #${TOAST_CONTAINER_ID}.bottom-left .cartridge-toast {
+      align-self: flex-start;
+    }
+
+    #${TOAST_CONTAINER_ID}.top-center .cartridge-toast,
+    #${TOAST_CONTAINER_ID}.bottom-center .cartridge-toast {
+      align-self: center;
+    }
+
+    @keyframes cartridge-toast-slide-in {
+      from {
+        opacity: 0;
+        transform: translateY(10px);
+      }
+      to {
+        opacity: 1;
+        transform: translateY(0);
+      }
+    }
+
+    .cartridge-toast.closing {
+      animation: cartridge-toast-slide-out 0.2s ease-in forwards;
+    }
+
+    @keyframes cartridge-toast-slide-out {
+      from {
+        opacity: 1;
+        transform: translateY(0);
+      }
+      to {
+        opacity: 0;
+        transform: translateY(10px);
+      }
+    }
+
+    @media (max-width: 640px) {
+      .cartridge-toast {
+        min-width: calc(100vw - 40px);
+        max-width: calc(100vw - 40px);
+      }
+
+      #${TOAST_CONTAINER_ID}.top-left,
+      #${TOAST_CONTAINER_ID}.top-right,
+      #${TOAST_CONTAINER_ID}.top-center {
+        top: 10px;
+        left: 20px;
+        right: 20px;
+        transform: none;
+        align-items: stretch;
+      }
+
+      #${TOAST_CONTAINER_ID}.bottom-left,
+      #${TOAST_CONTAINER_ID}.bottom-right,
+      #${TOAST_CONTAINER_ID}.bottom-center {
+        bottom: 10px;
+        left: 20px;
+        right: 20px;
+        transform: none;
+        align-items: stretch;
+      }
+    }
+  `;
+}

package/src/toast/types.ts

@@ -0,0 +1,67 @@
+export type ToastPosition =
+  | "top-left"
+  | "top-right"
+  | "top-center"
+  | "bottom-left"
+  | "bottom-right"
+  | "bottom-center";
+
+// Base toast options shared by all variants
+export interface BaseToastOptions {
+  duration?: number; // in milliseconds, 0 means persistent
+  position?: ToastPosition;
+}
+
+// Error Toast
+export interface ErrorToastOptions extends BaseToastOptions {
+  variant: "error";
+  message: string;
+}
+
+// Transaction Toast
+export interface TransactionToastOptions extends BaseToastOptions {
+  variant: "transaction";
+  status: "confirming" | "confirmed";
+  isExpanded?: boolean;
+  label?: string;
+}
+
+// Network Switch Toast
+export interface NetworkSwitchToastOptions extends BaseToastOptions {
+  variant: "network-switch";
+  networkName: string;
+  networkIcon?: string;
+}
+
+// Achievement Toast
+export interface AchievementToastOptions extends BaseToastOptions {
+  variant: "achievement";
+  title: string;
+  subtitle?: string;
+  xpAmount: number;
+  isDraft?: boolean;
+}
+
+// Quest Toast
+export interface QuestToastOptions extends BaseToastOptions {
+  variant: "quest";
+  title: string;
+  subtitle: string;
+}
+
+// Marketplace Toast
+export interface MarketplaceToastOptions extends BaseToastOptions {
+  variant: "marketplace";
+  itemName: string;
+  itemImage: string;
+  action: "purchased" | "sold";
+}
+
+// Union type for all toast variants
+export type ToastOptions =
+  | ErrorToastOptions
+  | TransactionToastOptions
+  | NetworkSwitchToastOptions
+  | AchievementToastOptions
+  | QuestToastOptions
+  | MarketplaceToastOptions;

package/src/toast/utils/progress-bar.ts

@@ -0,0 +1,23 @@
+import { ProgressBar } from "../components/progress-bar";
+
+/**
+ * Add a progress bar to a toast element
+ *
+ * @param toast - The toast element to add the progress bar to
+ * @param duration - Duration in milliseconds
+ * @param onComplete - Callback when progress completes
+ * @param borderRadius - Optional border radius in pixels (default: 8px)
+ */
+export function addProgressBarToToast(
+  toast: HTMLElement,
+  duration: number,
+  onComplete: () => void,
+  borderRadius?: number,
+): void {
+  const progressBar = ProgressBar({
+    duration,
+    onComplete,
+    borderRadius,
+  });
+  toast.appendChild(progressBar);
+}

package/src/toast/utils.ts

@@ -0,0 +1,65 @@
+export const TOAST_CONTAINER_ID = "cartridge-toast-container";
+export const DEFAULT_DURATION = 3000;
+export const DEFAULT_POSITION = "bottom-right";
+export const TOAST_MESSAGE_TYPE = "cartridge-toast-show";
+
+// Check if we're in an iframe
+export function isInIframe(): boolean {
+  try {
+    return typeof window !== "undefined" && window.self !== window.top;
+  } catch {
+    return true; // If we can't access window.top, we're likely in an iframe
+  }
+}
+
+// Get the target document (parent if in iframe, current if not)
+export function getTargetDocument(): Document | null {
+  if (typeof document === "undefined") {
+    return null;
+  }
+
+  if (isInIframe()) {
+    try {
+      // Try to access parent document
+      if (window.parent && window.parent.document) {
+        return window.parent.document;
+      }
+    } catch (e) {
+      console.warn("Failed to access parent document:", e);
+      return null;
+    }
+  }
+
+  return document;
+}
+
+// Get or create toast container
+export function getToastContainer(
+  targetDoc: Document,
+  position: string,
+): HTMLElement {
+  let container = targetDoc.getElementById(TOAST_CONTAINER_ID);
+
+  if (!container) {
+    container = targetDoc.createElement("div");
+    container.id = TOAST_CONTAINER_ID;
+    if (targetDoc.body) {
+      targetDoc.body.appendChild(container);
+    }
+  }
+
+  // Update position class
+  container.className = position;
+
+  return container;
+}
+
+// Remove toast with animation
+export function removeToast(toast: HTMLElement): void {
+  toast.classList.add("closing");
+  setTimeout(() => {
+    if (toast.parentNode) {
+      toast.parentNode.removeChild(toast);
+    }
+  }, 200);
+}