@farcaster/snap 1.15.3 → 1.16.0

package/src/react-native/index.tsx

@@ -1,289 +1,73 @@
-import type { Spec } from "@json-render/core";
-import { snapJsonRenderCatalog } from "@farcaster/snap/ui";
-import { SnapCatalogView } from "./catalog-renderer";
-import {
-  SnapThemeProvider,
-  useSnapTheme,
-  type SnapNativeColors,
-} from "./theme";
+import type { ReactNode } from "react";
+import type { ValidationResult } from "@farcaster/snap";
+import { SPEC_VERSION_2 } from "@farcaster/snap";
+import type { SnapNativeColors } from "./theme";
+import type { JsonValue, SnapPage, SnapActionHandlers } from "./types";
+import { useSnapTheme } from "./theme";
 import { hexToRgba } from "./use-snap-palette";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { ActivityIndicator, StyleSheet, View } from "react-native";
-import { ConfettiOverlay } from "./confetti-overlay";
-import {
-  DEFAULT_THEME_ACCENT,
-  PALETTE_LIGHT_HEX,
-  PALETTE_DARK_HEX,
-  type PaletteColor,
-} from "@farcaster/snap";
+import { SnapCardV1 } from "./v1/snap-view";
+import { SnapCardV2 } from "./v2/snap-view";
 
 // ─── Public types ──────────────────────────────────────
 
-export type JsonValue =
-  | string
-  | number
-  | boolean
-  | null
-  | JsonValue[]
-  | { [key: string]: JsonValue };
-
-export type SnapPage = {
-  version: string;
-  theme?: { accent?: string };
-  effects?: string[];
-  ui: Spec;
-};
-
-export type SnapActionHandlers = {
-  submit: (target: string, inputs: Record<string, JsonValue>) => void;
-  open_url: (target: string) => void;
-  open_mini_app: (target: string) => void;
-  view_cast: (params: { hash: string }) => void;
-  view_profile: (params: { fid: number }) => void;
-  compose_cast: (params: {
-    text?: string;
-    channelKey?: string;
-    embeds?: string[];
-  }) => void;
-  view_token: (params: { token: string }) => void;
-  send_token: (params: {
-    token: string;
-    amount?: string;
-    recipientFid?: number;
-    recipientAddress?: string;
-  }) => void;
-  swap_token: (params: { sellToken?: string; buyToken?: string }) => void;
-};
+export type { JsonValue, SnapPage, SnapActionHandlers } from "./types";
 
 // ─── Re-exports ───────────────────────────────────────
 
 export { useSnapTheme, hexToRgba };
 export type { SnapNativeColors };
 
-// ─── Internal helpers ─────────────────────────────────
-
-function applyStatePaths(
-  model: Record<string, unknown>,
-  changes: { path: string; value: unknown }[] | Record<string, unknown>,
-): void {
-  const entries = Array.isArray(changes)
-    ? changes.map((c) => [c.path, c.value] as const)
-    : Object.entries(changes);
-  for (const [path, value] of entries) {
-    const trimmed = path.startsWith("/") ? path : `/${path}`;
-    const parts = trimmed.split("/").filter(Boolean);
-    if (parts.length < 2) continue;
-    const [top, ...rest] = parts;
-    if (top === "inputs") {
-      if (typeof model.inputs !== "object" || model.inputs === null) {
-        model.inputs = {};
-      }
-      const inputs = model.inputs as Record<string, unknown>;
-      if (rest.length === 1) {
-        inputs[rest[0]!] = value;
-      }
-      continue;
-    }
-    if (top === "theme") {
-      if (typeof model.theme !== "object" || model.theme === null) {
-        model.theme = {};
-      }
-      const theme = model.theme as Record<string, unknown>;
-      if (rest.length === 1) {
-        theme[rest[0]!] = value;
-      }
-    }
-  }
-}
-
-function resolveAccentHex(
-  accent: string | undefined,
-  appearance: "light" | "dark",
-): string {
-  const map = appearance === "dark" ? PALETTE_DARK_HEX : PALETTE_LIGHT_HEX;
-  const name =
-    accent && Object.hasOwn(map, accent)
-      ? (accent as PaletteColor)
-      : DEFAULT_THEME_ACCENT;
-  return map[name];
-}
-
-// ─── SnapView ─────────────────────────────────────────
+// ─── SnapCard (version-switching) ─────────────────────
 
-function SnapViewInner({
-  snap,
-  handlers,
-  loading = false,
-}: {
-  snap: SnapPage;
-  handlers: SnapActionHandlers;
-  loading?: boolean;
-}) {
-  const { mode } = useSnapTheme();
-  const spec = snap.ui;
-  const accentHex = resolveAccentHex(snap.theme?.accent, mode);
-
-  const showConfetti = snap.effects?.includes("confetti");
-
-  // Increment key each time a new snap with confetti arrives so the overlay
-  // unmounts/remounts and restarts its animation on every trigger.
-  const confettiEpochRef = useRef(0);
-  const lastConfettiSnapRef = useRef<typeof snap | null>(null);
-  if (showConfetti && snap !== lastConfettiSnapRef.current) {
-    confettiEpochRef.current++;
-    lastConfettiSnapRef.current = snap;
-  }
-
-  const initialState = useMemo(
-    () => ({
-      ...(spec.state ?? {}),
-      inputs: { ...((spec.state?.inputs ?? {}) as Record<string, unknown>) },
-      theme: {
-        ...((spec.state?.theme ?? {}) as Record<string, unknown>),
-        ...(snap.theme ? { accent: snap.theme.accent } : {}),
-      },
-    }),
-    [spec, snap.theme],
-  );
-
-  const stateRef = useRef<Record<string, unknown>>(initialState);
-
-  useEffect(() => {
-    stateRef.current = {
-      inputs: {
-        ...((initialState.inputs ?? {}) as Record<string, unknown>),
-      },
-      theme: {
-        ...((initialState.theme ?? {}) as Record<string, unknown>),
-      },
-    };
-  }, [initialState]);
-
-  useEffect(() => {
-    const result = snapJsonRenderCatalog.validate(spec);
-    if (!result.success) {
-      // eslint-disable-next-line no-console
-      console.warn("[SnapView] catalog validation issues:", result.error);
-    }
-  }, [spec]);
-
-  const [pageKey, setPageKey] = useState(0);
-  useEffect(() => {
-    setPageKey((k) => k + 1);
-  }, [spec]);
-
-  const handlersRef = useRef(handlers);
-  handlersRef.current = handlers;
-
-  const handleAction = useCallback((name: unknown, params: unknown) => {
-    const inputs = (stateRef.current.inputs ?? {}) as Record<string, JsonValue>;
-    const p = (params ?? {}) as Record<string, unknown>;
-    const h = handlersRef.current;
-    switch (name) {
-      case "submit":
-        h.submit(String(p.target ?? ""), inputs);
-        break;
-      case "open_url":
-        h.open_url(String(p.target ?? ""));
-        break;
-      case "open_mini_app":
-        h.open_mini_app(String(p.target ?? ""));
-        break;
-      case "view_cast":
-        h.view_cast({ hash: String(p.hash ?? "") });
-        break;
-      case "view_profile":
-        h.view_profile({ fid: Number(p.fid ?? 0) });
-        break;
-      case "compose_cast":
-        h.compose_cast({
-          text: p.text ? String(p.text) : undefined,
-          channelKey: p.channelKey ? String(p.channelKey) : undefined,
-          embeds: Array.isArray(p.embeds) ? (p.embeds as string[]) : undefined,
-        });
-        break;
-      case "view_token":
-        h.view_token({ token: String(p.token ?? "") });
-        break;
-      case "send_token":
-        h.send_token({
-          token: String(p.token ?? ""),
-          amount: p.amount ? String(p.amount) : undefined,
-          recipientFid: p.recipientFid ? Number(p.recipientFid) : undefined,
-          recipientAddress: p.recipientAddress
-            ? String(p.recipientAddress)
-            : undefined,
-        });
-        break;
-      case "swap_token":
-        h.swap_token({
-          sellToken: p.sellToken ? String(p.sellToken) : undefined,
-          buyToken: p.buyToken ? String(p.buyToken) : undefined,
-        });
-        break;
-      default:
-        break;
-    }
-  }, []);
-
-  return (
-    <View style={styles.container}>
-      {loading ? (
-        <View
-          style={[
-            styles.overlay,
-            {
-              backgroundColor:
-                mode === "dark" ? "rgba(0,0,0,0.1)" : "rgba(255,255,255,0.2)",
-            },
-          ]}
-        >
-          <ActivityIndicator size="large" color={accentHex} />
-        </View>
-      ) : null}
-      {showConfetti ? <ConfettiOverlay key={`confetti-${confettiEpochRef.current}`} /> : null}
-      <SnapCatalogView
-        key={pageKey}
-        spec={spec}
-        state={initialState}
-        loading={false}
-        onStateChange={(changes) => {
-          applyStatePaths(stateRef.current, changes);
-        }}
-        onAction={handleAction}
-      />
-    </View>
-  );
-}
-
-export function SnapView({
+export function SnapCard({
   snap,
   handlers,
   loading = false,
   appearance = "dark",
   colors,
+  borderRadius = 16,
+  showOverflowWarning = false,
+  onValidationError,
+  validationErrorFallback,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
   loading?: boolean;
   appearance?: "light" | "dark";
   colors?: Partial<SnapNativeColors>;
+  /** Border radius of the card (default 16). */
+  borderRadius?: number;
+  /** When true (v2 only), extends to 700px and shows a warning overlay below 500px. When false, clips at 500px. */
+  showOverflowWarning?: boolean;
+  /** Called when snap validation fails (v2 only). */
+  onValidationError?: (result: ValidationResult) => void;
+  /** Custom fallback rendered when validation fails (v2 only). */
+  validationErrorFallback?: ReactNode;
 }) {
+  if (snap.version === SPEC_VERSION_2) {
+    return (
+      <SnapCardV2
+        snap={snap}
+        handlers={handlers}
+        loading={loading}
+        appearance={appearance}
+        colors={colors}
+        borderRadius={borderRadius}
+        showOverflowWarning={showOverflowWarning}
+        onValidationError={onValidationError}
+        validationErrorFallback={validationErrorFallback}
+      />
+    );
+  }
+
   return (
-    <SnapThemeProvider appearance={appearance} colors={colors}>
-      <SnapViewInner snap={snap} handlers={handlers} loading={loading} />
-    </SnapThemeProvider>
+    <SnapCardV1
+      snap={snap}
+      handlers={handlers}
+      loading={loading}
+      appearance={appearance}
+      colors={colors}
+      borderRadius={borderRadius}
+    />
   );
 }
-
-const styles = StyleSheet.create({
-  container: {
-    width: "100%",
-  },
-  overlay: {
-    ...StyleSheet.absoluteFillObject,
-    alignItems: "center",
-    justifyContent: "center",
-    zIndex: 10,
-  },
-});

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

@@ -0,0 +1,209 @@
+import type { Spec } from "@json-render/core";
+import { snapJsonRenderCatalog } from "@farcaster/snap/ui";
+import { SnapCatalogView } from "./catalog-renderer";
+import { useSnapTheme } from "./theme";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { ActivityIndicator, StyleSheet, View } from "react-native";
+import {
+  DEFAULT_THEME_ACCENT,
+  PALETTE_LIGHT_HEX,
+  PALETTE_DARK_HEX,
+  type PaletteColor,
+} from "@farcaster/snap";
+import type { SnapPage, SnapActionHandlers, JsonValue } from "./types";
+
+// ─── Shared helpers ──────────────────────────────────
+
+export function applyStatePaths(
+  model: Record<string, unknown>,
+  changes: { path: string; value: unknown }[] | Record<string, unknown>,
+): void {
+  const entries = Array.isArray(changes)
+    ? changes.map((c) => [c.path, c.value] as const)
+    : Object.entries(changes);
+  for (const [path, value] of entries) {
+    const trimmed = path.startsWith("/") ? path : `/${path}`;
+    const parts = trimmed.split("/").filter(Boolean);
+    if (parts.length < 2) continue;
+    const [top, ...rest] = parts;
+    if (top === "inputs") {
+      if (typeof model.inputs !== "object" || model.inputs === null) {
+        model.inputs = {};
+      }
+      const inputs = model.inputs as Record<string, unknown>;
+      if (rest.length === 1) {
+        inputs[rest[0]!] = value;
+      }
+      continue;
+    }
+    if (top === "theme") {
+      if (typeof model.theme !== "object" || model.theme === null) {
+        model.theme = {};
+      }
+      const theme = model.theme as Record<string, unknown>;
+      if (rest.length === 1) {
+        theme[rest[0]!] = value;
+      }
+    }
+  }
+}
+
+export function resolveAccentHex(
+  accent: string | undefined,
+  appearance: "light" | "dark",
+): string {
+  const map = appearance === "dark" ? PALETTE_DARK_HEX : PALETTE_LIGHT_HEX;
+  const name =
+    accent && Object.hasOwn(map, accent)
+      ? (accent as PaletteColor)
+      : DEFAULT_THEME_ACCENT;
+  return map[name];
+}
+
+// ─── Core rendering component (no validation) ────────
+
+export function SnapViewCoreInner({
+  snap,
+  handlers,
+  loading = false,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+}) {
+  const { mode } = useSnapTheme();
+  const spec = snap.ui;
+  const accentHex = resolveAccentHex(snap.theme?.accent, mode);
+
+  const initialState = useMemo(
+    () => ({
+      ...(spec.state ?? {}),
+      inputs: { ...((spec.state?.inputs ?? {}) as Record<string, unknown>) },
+      theme: {
+        ...((spec.state?.theme ?? {}) as Record<string, unknown>),
+        ...(snap.theme ? { accent: snap.theme.accent } : {}),
+      },
+    }),
+    [spec, snap.theme],
+  );
+
+  const stateRef = useRef<Record<string, unknown>>(initialState);
+
+  useEffect(() => {
+    stateRef.current = {
+      inputs: {
+        ...((initialState.inputs ?? {}) as Record<string, unknown>),
+      },
+      theme: {
+        ...((initialState.theme ?? {}) as Record<string, unknown>),
+      },
+    };
+  }, [initialState]);
+
+  useEffect(() => {
+    const catalogResult = snapJsonRenderCatalog.validate(spec);
+    if (!catalogResult.success) {
+      // eslint-disable-next-line no-console
+      console.warn("[Snap] catalog validation issues:", catalogResult.error);
+    }
+  }, [spec]);
+
+  const [pageKey, setPageKey] = useState(0);
+  useEffect(() => {
+    setPageKey((k) => k + 1);
+  }, [spec]);
+
+  const handlersRef = useRef(handlers);
+  handlersRef.current = handlers;
+
+  const handleAction = useCallback((name: unknown, params: unknown) => {
+    const inputs = (stateRef.current.inputs ?? {}) as Record<string, JsonValue>;
+    const p = (params ?? {}) as Record<string, unknown>;
+    const h = handlersRef.current;
+    switch (name) {
+      case "submit":
+        h.submit(String(p.target ?? ""), inputs);
+        break;
+      case "open_url":
+        h.open_url(String(p.target ?? ""));
+        break;
+      case "open_mini_app":
+        h.open_mini_app(String(p.target ?? ""));
+        break;
+      case "view_cast":
+        h.view_cast({ hash: String(p.hash ?? "") });
+        break;
+      case "view_profile":
+        h.view_profile({ fid: Number(p.fid ?? 0) });
+        break;
+      case "compose_cast":
+        h.compose_cast({
+          text: p.text ? String(p.text) : undefined,
+          channelKey: p.channelKey ? String(p.channelKey) : undefined,
+          embeds: Array.isArray(p.embeds) ? (p.embeds as string[]) : undefined,
+        });
+        break;
+      case "view_token":
+        h.view_token({ token: String(p.token ?? "") });
+        break;
+      case "send_token":
+        h.send_token({
+          token: String(p.token ?? ""),
+          amount: p.amount ? String(p.amount) : undefined,
+          recipientFid: p.recipientFid ? Number(p.recipientFid) : undefined,
+          recipientAddress: p.recipientAddress
+            ? String(p.recipientAddress)
+            : undefined,
+        });
+        break;
+      case "swap_token":
+        h.swap_token({
+          sellToken: p.sellToken ? String(p.sellToken) : undefined,
+          buyToken: p.buyToken ? String(p.buyToken) : undefined,
+        });
+        break;
+      default:
+        break;
+    }
+  }, []);
+
+  return (
+    <View style={styles.container}>
+      {loading ? (
+        <View
+          style={[
+            styles.overlay,
+            {
+              backgroundColor:
+                mode === "dark" ? "rgba(0,0,0,0.1)" : "rgba(255,255,255,0.2)",
+            },
+          ]}
+        >
+          <ActivityIndicator size="large" color={accentHex} />
+        </View>
+      ) : null}
+      <SnapCatalogView
+        key={pageKey}
+        spec={spec}
+        state={initialState}
+        loading={false}
+        onStateChange={(changes) => {
+          applyStatePaths(stateRef.current, changes);
+        }}
+        onAction={handleAction}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    width: "100%",
+  },
+  overlay: {
+    ...StyleSheet.absoluteFillObject,
+    alignItems: "center",
+    justifyContent: "center",
+    zIndex: 10,
+  },
+});

package/src/react-native/types.ts

@@ -0,0 +1,37 @@
+import type { Spec } from "@json-render/core";
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type SnapPage = {
+  version: string;
+  theme?: { accent?: string };
+  effects?: string[];
+  ui: Spec;
+};
+
+export type SnapActionHandlers = {
+  submit: (target: string, inputs: Record<string, JsonValue>) => void;
+  open_url: (target: string) => void;
+  open_mini_app: (target: string) => void;
+  view_cast: (params: { hash: string }) => void;
+  view_profile: (params: { fid: number }) => void;
+  compose_cast: (params: {
+    text?: string;
+    channelKey?: string;
+    embeds?: string[];
+  }) => void;
+  view_token: (params: { token: string }) => void;
+  send_token: (params: {
+    token: string;
+    amount?: string;
+    recipientFid?: number;
+    recipientAddress?: string;
+  }) => void;
+  swap_token: (params: { sellToken?: string; buyToken?: string }) => void;
+};

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

@@ -0,0 +1,108 @@
+import { View, StyleSheet } from "react-native";
+import { SnapThemeProvider, useSnapTheme, type SnapNativeColors } from "../theme";
+import { SnapViewCoreInner } from "../snap-view-core";
+import type { SnapPage, SnapActionHandlers } from "../types";
+
+// ─── SnapViewV1 (no validation, no height limits) ────
+
+export function SnapViewV1Inner({
+  snap,
+  handlers,
+  loading = false,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+}) {
+  return (
+    <SnapViewCoreInner snap={snap} handlers={handlers} loading={loading} />
+  );
+}
+
+export function SnapViewV1({
+  snap,
+  handlers,
+  loading = false,
+  appearance = "dark",
+  colors,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  appearance?: "light" | "dark";
+  colors?: Partial<SnapNativeColors>;
+}) {
+  return (
+    <SnapThemeProvider appearance={appearance} colors={colors}>
+      <SnapViewV1Inner snap={snap} handlers={handlers} loading={loading} />
+    </SnapThemeProvider>
+  );
+}
+
+// ─── SnapCardV1 (card frame, no height limits) ───────
+
+function SnapCardV1Inner({
+  snap,
+  handlers,
+  loading = false,
+  borderRadius,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  borderRadius: number;
+}) {
+  const { colors } = useSnapTheme();
+
+  return (
+    <View style={cardStyles.frameRing}>
+      <View
+        style={[
+          cardStyles.card,
+          {
+            borderRadius,
+            borderColor: colors.border,
+            backgroundColor: colors.surface,
+          },
+        ]}
+      >
+        <View style={cardStyles.body}>
+          <SnapViewV1Inner snap={snap} handlers={handlers} loading={loading} />
+        </View>
+      </View>
+    </View>
+  );
+}
+
+export function SnapCardV1({
+  snap,
+  handlers,
+  loading = false,
+  appearance = "dark",
+  colors,
+  borderRadius = 16,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  appearance?: "light" | "dark";
+  colors?: Partial<SnapNativeColors>;
+  borderRadius?: number;
+}) {
+  return (
+    <SnapThemeProvider appearance={appearance} colors={colors}>
+      <SnapCardV1Inner
+        snap={snap}
+        handlers={handlers}
+        loading={loading}
+        borderRadius={borderRadius}
+      />
+    </SnapThemeProvider>
+  );
+}
+
+const cardStyles = StyleSheet.create({
+  frameRing: { alignSelf: "stretch" },
+  card: { overflow: "hidden", borderWidth: 1, minHeight: 120 },
+  body: { paddingHorizontal: 16, paddingVertical: 16 },
+});