@farcaster/snap 2.9.0 → 2.10.0

package/src/react/components/action-button.tsx

@@ -1,7 +1,7 @@
 "use client";
 
-import { useState } from "react";
-import { useStateStore } from "@json-render/react";
+import { useMemo, useState } from "react";
+import { useStateStore, useStateValue } from "@json-render/react";
 import { ExternalLink } from "lucide-react";
 import { Button } from "@neynar/ui/button";
 import { cn } from "@neynar/ui/utils";
@@ -10,6 +10,7 @@ import {
   getPaginatorAction,
   runPaginatorAction,
 } from "../../ui/paginator-state";
+import { buildActionActivityStateChanges } from "../../render-state";
 import { useSnapStackDirection } from "../stack-direction-context";
 import { ICON_MAP } from "./icon";
 
@@ -24,6 +25,22 @@ function isExternalLinkAction(
   return press.action === "open_url";
 }
 
+function getActionPendingPath(on: Record<string, unknown> | undefined) {
+  const press = on?.press as
+    | { action?: unknown; params?: Record<string, unknown> }
+    | undefined;
+  if (!press?.action) return "/__snap/action/pending";
+
+  return (
+    buildActionActivityStateChanges({
+      actionName: press.action,
+      params: press.params ?? {},
+      pending: true,
+    }).find((change) => change.path.endsWith("/pending"))?.path ??
+    "/__snap/action/pending"
+  );
+}
+
 export function SnapActionButton({
   element,
   emit,
@@ -38,18 +55,25 @@ export function SnapActionButton({
   const label = String(props.label ?? "Action");
   const variant = String(props.variant ?? "secondary");
   const isPrimary = variant === "primary";
+  const disabled = props.disabled === true;
   const iconName = props.icon ? String(props.icon) : undefined;
   const colors = useSnapColors();
   const [hovered, setHovered] = useState(false);
   const stateStore = useStateStore();
   const paginatorAction = getPaginatorAction(element.on);
+  const actionPendingPath = useMemo(
+    () => getActionPendingPath(element.on),
+    [element.on],
+  );
+  const actionPending = useStateValue(actionPendingPath) === true;
 
   const Icon = iconName ? ICON_MAP[iconName] : undefined;
   const showExternalIcon = isExternalLinkAction(element.on);
   const inHorizontalStack = useSnapStackDirection() === "horizontal";
 
   const style = {
-    cursor: "pointer" as const,
+    cursor: disabled ? ("not-allowed" as const) : ("pointer" as const),
+    opacity: disabled ? 0.62 : 1,
     ...(isPrimary
       ? {
           backgroundColor: hovered ? colors.accentHover : colors.accent,
@@ -83,8 +107,10 @@ export function SnapActionButton({
         type="button"
         variant={isPrimary ? "default" : "secondary"}
         className={cn("h-8 w-full gap-2 px-3 text-sm")}
+        disabled={disabled}
         style={style}
         onClick={() => {
+          if (disabled) return;
           if (!runPaginatorAction(stateStore, paginatorAction)) {
             emit("press");
           }
@@ -94,6 +120,9 @@ export function SnapActionButton({
       >
         {Icon && <Icon size={16} />}
         {label}
+        {actionPending && (
+          <span data-snap-action-pending-active="true" hidden />
+        )}
         {showExternalIcon && (
           <ExternalLink size={14} style={{ opacity: 0.6 }} />
         )}

package/src/react/index.tsx

@@ -5,6 +5,7 @@ import type { ReactNode } from "react";
 import type { ValidationResult } from "../validator.js";
 import { SPEC_VERSION_2 } from "../constants";
 import type { SnapRenderState } from "../render-state";
+import type { SnapTransactionResult } from "../schemas";
 import { SnapCardV1 } from "./v1/snap-view";
 import { SnapCardV2 } from "./v2/snap-view";
 
@@ -57,7 +58,9 @@ export type SnapActionHandlers = {
     recipientAddress?: string;
   }) => void;
   swap_token: (params: { sellToken?: string; buyToken?: string }) => void;
-  send_transaction?: (params: SnapSendTransactionParams) => void;
+  send_transaction?: (
+    params: SnapSendTransactionParams,
+  ) => void | Promise<void | SnapTransactionResult>;
 };
 
 export type { SnapRenderState };

package/src/react/snap-view-core.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import type { Spec } from "@json-render/core";
+import { createStateStore } from "@json-render/react";
 import { snapJsonRenderCatalog } from "../ui/index.js";
 import { SnapCatalogView } from "./catalog-renderer";
 import { SnapPreviewAccentProvider } from "./accent-context";
@@ -8,10 +9,11 @@ import { SnapVersionProvider } from "./snap-version-context";
 import { resolveSnapPaletteHex } from "./lib/resolve-palette-hex";
 import { snapPreviewPrimaryCssProperties } from "./lib/preview-primary-css";
 import {
-  applyStatePaths,
+  buildActionActivityStateChanges,
   buildInitialRenderState,
   cloneSnapRenderState,
   getUnpresentedSnapEffects,
+  hasPendingSnapAction,
   markSnapEffectsPresented,
   type SnapRenderState,
 } from "../render-state";
@@ -36,6 +38,12 @@ function optionalString(value: unknown): string | undefined {
   return value ? String(value) : undefined;
 }
 
+function recordValue(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
 function withDefaultElementProps(spec: Spec): Spec {
   if (!spec || typeof spec !== "object" || !("elements" in spec)) return spec;
   const elements = spec.elements as unknown as Record<
@@ -266,6 +274,8 @@ export function SnapLoadingOverlay({
 
   return (
     <div
+      data-snap-loading-overlay
+      data-snap-loading-active={active ? "true" : "false"}
       style={{
         position: "absolute",
         inset: 0,
@@ -299,6 +309,20 @@ export function SnapLoadingOverlay({
         }}
       />
       <style>{`
+        [data-snap-view-root]:has([data-snap-action-pending-active="true"])
+          [data-snap-loading-overlay] {
+          opacity: 1 !important;
+          pointer-events: auto !important;
+          backdrop-filter: blur(10px) saturate(1.05) !important;
+          -webkit-backdrop-filter: blur(10px) saturate(1.05) !important;
+        }
+        [data-snap-card-surface]:has([data-snap-action-pending-active="true"])
+          > [data-snap-loading-overlay] {
+          opacity: 1 !important;
+          pointer-events: auto !important;
+          backdrop-filter: blur(10px) saturate(1.05) !important;
+          -webkit-backdrop-filter: blur(10px) saturate(1.05) !important;
+        }
         @keyframes snapViewSpin {
           to { transform: rotate(360deg); }
         }
@@ -314,6 +338,22 @@ export function SnapLoadingOverlay({
   );
 }
 
+function SnapPendingActionOverlay({
+  appearance,
+  accentHex,
+}: {
+  appearance: "light" | "dark";
+  accentHex: string;
+}) {
+  return (
+    <SnapLoadingOverlay
+      appearance={appearance}
+      accentHex={accentHex}
+      active={false}
+    />
+  );
+}
+
 const PALETTE = [
   "gray",
   "blue",
@@ -360,12 +400,31 @@ export function SnapViewCore({
     [initialRenderState, spec.state, snap.theme?.accent],
   );
 
+  const stateStore = useMemo(() => createStateStore(initialState), [
+    initialState,
+  ]);
   const stateRef = useRef<Record<string, unknown>>(initialState);
+  const onRenderStateChangeRef = useRef(onRenderStateChange);
+  const pendingActionCountRef = useRef(0);
 
   useEffect(() => {
     stateRef.current = cloneSnapRenderState(initialState);
   }, [initialState]);
 
+  useEffect(() => {
+    onRenderStateChangeRef.current = onRenderStateChange;
+  }, [onRenderStateChange]);
+
+  useEffect(
+    () =>
+      stateStore.subscribe(() => {
+        const snapshot = cloneSnapRenderState(stateStore.getSnapshot());
+        stateRef.current = snapshot;
+        onRenderStateChangeRef.current?.(snapshot);
+      }),
+    [stateStore],
+  );
+
   useEffect(() => {
     const catalogResult = snapJsonRenderCatalog.validate(spec);
     if (!catalogResult.success) {
@@ -390,10 +449,6 @@ export function SnapViewCore({
     confetti: 0,
     fireworks: 0,
   });
-  const onRenderStateChangeRef = useRef(onRenderStateChange);
-  useEffect(() => {
-    onRenderStateChangeRef.current = onRenderStateChange;
-  }, [onRenderStateChange]);
   useEffect(() => {
     const effectsToPresent = getUnpresentedSnapEffects(
       stateRef.current,
@@ -415,7 +470,10 @@ export function SnapViewCore({
     }
 
     if (markSnapEffectsPresented(stateRef.current, effectsToPresent)) {
-      onRenderStateChangeRef.current?.(cloneSnapRenderState(stateRef.current));
+      const meta = recordValue(stateRef.current.__snapRender);
+      stateStore.update({
+        "/__snapRender/presentedEffects": meta?.presentedEffects ?? [],
+      });
     }
 
     setEffectRunKeys((current) => ({
@@ -430,7 +488,7 @@ export function SnapViewCore({
           ? current.fireworks
           : 0,
     }));
-  }, [initialState, showConfetti, showFireworks, snapEffects]);
+  }, [initialState, showConfetti, showFireworks, snapEffects, stateStore]);
 
   const accentName = snap.theme?.accent ?? "purple";
 
@@ -449,6 +507,40 @@ export function SnapViewCore({
     } as CSSProperties;
   }, [accentName, appearance]);
 
+  const applyActionActivityState = useCallback(
+    (name: unknown, params: Record<string, unknown>, pending: boolean) => {
+      stateStore.update(
+        Object.fromEntries(
+          buildActionActivityStateChanges({
+            actionName: name,
+            params,
+            pending,
+          }).map(({ path, value }) => [path, value]),
+        ),
+      );
+    },
+    [stateStore],
+  );
+
+  const setActionPending = useCallback(
+    (name: unknown, params: Record<string, unknown>) => {
+      pendingActionCountRef.current += 1;
+      applyActionActivityState(name, params, true);
+    },
+    [applyActionActivityState],
+  );
+
+  const setActionSettled = useCallback(
+    (name: unknown, params: Record<string, unknown>) => {
+      pendingActionCountRef.current = Math.max(
+        0,
+        pendingActionCountRef.current - 1,
+      );
+      applyActionActivityState(name, params, false);
+    },
+    [applyActionActivityState],
+  );
+
   const handleAction = useCallback(
     (name: unknown, params: unknown) => {
       const inputs = (stateRef.current.inputs ?? {}) as Record<
@@ -456,30 +548,35 @@ export function SnapViewCore({
         JsonValue
       >;
       const p = (params ?? {}) as Record<string, unknown>;
+      let result: unknown;
+      setActionPending(name, p);
+
       switch (name) {
         case "submit":
-          handlers.submit(String(p.target ?? ""), inputs);
+          result = handlers.submit(String(p.target ?? ""), inputs);
           break;
         case "open_url":
-          handlers.open_url(String(p.target ?? ""));
+          result = handlers.open_url(String(p.target ?? ""));
           break;
         case "open_snap":
-          handlers.open_snap(String(p.target ?? ""));
+          result = handlers.open_snap(String(p.target ?? ""));
           break;
         case "open_mini_app":
-          handlers.open_mini_app(String(p.target ?? ""));
+          result = handlers.open_mini_app(String(p.target ?? ""));
           break;
         case "view_cast":
-          handlers.view_cast({ hash: String(p.hash ?? "") });
+          result = handlers.view_cast({ hash: String(p.hash ?? "") });
           break;
         case "view_profile":
-          handlers.view_profile({ fid: Number(p.fid ?? 0) });
+          result = handlers.view_profile({ fid: Number(p.fid ?? 0) });
           break;
         case "view_channel":
-          handlers.view_channel({ channelKey: String(p.channelKey ?? "") });
+          result = handlers.view_channel({
+            channelKey: String(p.channelKey ?? ""),
+          });
           break;
         case "compose_cast":
-          handlers.compose_cast({
+          result = handlers.compose_cast({
             text: p.text ? String(p.text) : undefined,
             channelKey: p.channelKey ? String(p.channelKey) : undefined,
             embeds: Array.isArray(p.embeds)
@@ -488,10 +585,10 @@ export function SnapViewCore({
           });
           break;
         case "view_token":
-          handlers.view_token({ token: String(p.token ?? "") });
+          result = handlers.view_token({ token: String(p.token ?? "") });
           break;
         case "send_token":
-          handlers.send_token({
+          result = handlers.send_token({
             token: String(p.token ?? ""),
             amount: p.amount ? String(p.amount) : undefined,
             recipientFid: p.recipientFid ? Number(p.recipientFid) : undefined,
@@ -501,13 +598,13 @@ export function SnapViewCore({
           });
           break;
         case "swap_token":
-          handlers.swap_token({
+          result = handlers.swap_token({
             sellToken: p.sellToken ? String(p.sellToken) : undefined,
             buyToken: p.buyToken ? String(p.buyToken) : undefined,
           });
           break;
         case "send_transaction":
-          handlers.send_transaction?.({
+          result = handlers.send_transaction?.({
             chainId: String(p.chainId ?? ""),
             to: String(p.to ?? ""),
             data: optionalString(p.data),
@@ -521,12 +618,29 @@ export function SnapViewCore({
         default:
           break;
       }
+
+      if (result instanceof Promise) {
+        void result.finally(() => {
+          setActionSettled(name, p);
+        }).catch(() => {});
+      } else {
+        setActionSettled(name, p);
+      }
+      return result;
     },
-    [handlers],
+    [handlers, setActionPending, setActionSettled],
   );
 
   return (
-    <div style={{ position: "relative", width: "100%" }}>
+    <div
+      data-snap-view-root
+      style={{ position: "relative", width: "100%" }}
+      onClickCapture={(event) => {
+        if (!hasPendingSnapAction(stateRef.current)) return;
+        event.preventDefault();
+        event.stopPropagation();
+      }}
+    >
       {showConfetti && effectRunKeys.confetti > 0 && (
         <ConfettiOverlay key={effectRunKeys.confetti} />
       )}
@@ -552,14 +666,17 @@ export function SnapViewCore({
             <SnapCatalogView
               key={pageKey}
               spec={spec}
-              state={initialState}
+              store={stateStore}
               loading={false}
-              onStateChange={(changes) => {
-                applyStatePaths(stateRef.current, changes);
-                onRenderStateChange?.(cloneSnapRenderState(stateRef.current));
-              }}
               onAction={handleAction}
-            />
+            >
+              {loadingOverlay === undefined ? (
+                <SnapPendingActionOverlay
+                  appearance={appearance}
+                  accentHex={accentHex}
+                />
+              ) : null}
+            </SnapCatalogView>
           </SnapVersionProvider>
         </SnapPreviewAccentProvider>
       </div>

package/src/react/v1/snap-view.tsx

@@ -120,6 +120,7 @@ export function SnapCardV1({
       }}
     >
       <div
+        data-snap-card-surface
         style={{
           position: "relative",
           overflow: "hidden",

package/src/react/v2/snap-view.tsx

@@ -193,6 +193,7 @@ export function SnapCardV2({
       }}
     >
       <div
+        data-snap-card-surface
         style={{
           position: "relative",
           maxHeight: containerMaxHeight,

package/src/react-native/components/snap-action-button.tsx

@@ -34,6 +34,7 @@ export function SnapActionButton({
   const label = String(props.label ?? "Action");
   const variant = String(props.variant ?? "secondary");
   const isPrimary = variant === "primary";
+  const disabled = props.disabled === true;
   const iconName = props.icon ? String(props.icon) : undefined;
 
   const textColor = isPrimary ? "#fff" : colors.text;
@@ -53,10 +54,13 @@ export function SnapActionButton({
           isPrimary ? styles.btnDefault : styles.btnOther,
           isPrimary
             ? { backgroundColor: pressed ? accentHex + "DD" : accentHex }
-            : { backgroundColor: pressed ? colors.mutedHover : colors.muted },
+              : { backgroundColor: pressed ? colors.mutedHover : colors.muted },
           pressed && styles.pressed,
+          disabled && styles.disabled,
         ]}
+        disabled={disabled}
         onPress={() => {
+          if (disabled) return;
           if (runPaginatorAction(stateStore, paginatorAction)) return;
           void (async () => {
             try {
@@ -114,4 +118,5 @@ const styles = StyleSheet.create({
     paddingVertical: 6,
   },
   pressed: { opacity: 0.88 },
+  disabled: { opacity: 0.62 },
 });