@farcaster/snap 1.5.2 → 1.7.0

package/src/react/index.tsx

@@ -0,0 +1,321 @@
+"use client";
+
+import type { Spec } from "@json-render/core";
+import { snapJsonRenderCatalog } from "../ui/index.js";
+import { SnapCatalogView } from "./catalog-renderer";
+import { SnapPreviewAccentProvider } from "./accent-context";
+import { resolveSnapPaletteHex } from "./lib/resolve-palette-hex";
+import { snapPreviewPrimaryCssProperties } from "./lib/preview-primary-css";
+import {
+  type CSSProperties,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+// ─── 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;
+};
+
+// ─── 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;
+      }
+    }
+  }
+}
+
+const CONFETTI_COLORS = [
+  "#8B5CF6",
+  "#EC4899",
+  "#3B82F6",
+  "#10B981",
+  "#F59E0B",
+  "#EF4444",
+  "#06B6D4",
+];
+
+function ConfettiOverlay() {
+  const pieces = useMemo(
+    () =>
+      Array.from({ length: 80 }, (_, i) => ({
+        id: i,
+        left: Math.random() * 100,
+        delay: Math.random() * 1.2,
+        duration: 2.5 + Math.random() * 2,
+        color:
+          CONFETTI_COLORS[Math.floor(Math.random() * CONFETTI_COLORS.length)],
+        size: 6 + Math.random() * 8,
+        rotation: Math.random() * 360,
+      })),
+    [],
+  );
+
+  return (
+    <div
+      style={{
+        position: "absolute",
+        inset: 0,
+        overflow: "hidden",
+        pointerEvents: "none",
+        zIndex: 20,
+      }}
+    >
+      {pieces.map(({ id, left, delay, duration, color, size, rotation }) => (
+        <div
+          key={id}
+          style={{
+            position: "absolute",
+            left: `${left}%`,
+            top: -20,
+            width: size,
+            height: size * 0.6,
+            backgroundColor: color,
+            borderRadius: 2,
+            transform: `rotate(${rotation}deg)`,
+            animation: `confettiFall ${duration}s ease-in ${delay}s forwards`,
+          }}
+        />
+      ))}
+      <style>{`@keyframes confettiFall{0%{top:-20px;opacity:1;transform:rotate(0deg) translateX(0)}50%{opacity:1}100%{top:110%;opacity:0;transform:rotate(720deg) translateX(${Math.random() > 0.5 ? "" : "-"}40px)}}`}</style>
+    </div>
+  );
+}
+
+const PALETTE = [
+  "gray",
+  "blue",
+  "red",
+  "amber",
+  "green",
+  "teal",
+  "purple",
+  "pink",
+] as const;
+
+// ─── SnapView ──────────────────────────────────────────
+
+export function SnapView({
+  snap,
+  handlers,
+  loading = false,
+  appearance = "dark",
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  appearance?: "light" | "dark";
+}) {
+  const spec = snap.ui;
+  const initialState = useMemo(
+    () => spec.state ?? { inputs: {} },
+    [spec],
+  );
+
+  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 showConfetti = snap.effects?.includes("confetti");
+
+  const previewSurfaceStyle = useMemo(() => {
+    const vars: Record<string, string> = {};
+    for (const c of PALETTE)
+      vars[`--snap-color-${c}`] = resolveSnapPaletteHex(c, appearance);
+    return {
+      ...snapPreviewPrimaryCssProperties(
+        snap.theme?.accent ?? "purple",
+        appearance,
+      ),
+      ...vars,
+    } as CSSProperties;
+  }, [snap.theme?.accent, appearance]);
+
+  const handleAction = useCallback(
+    (name: unknown, params: unknown) => {
+      const inputs = (stateRef.current.inputs ?? {}) as Record<
+        string,
+        JsonValue
+      >;
+      const p = (params ?? {}) as Record<string, unknown>;
+      switch (name) {
+        case "submit":
+          handlers.submit(String(p.target ?? ""), inputs);
+          break;
+        case "open_url":
+          handlers.open_url(String(p.target ?? ""));
+          break;
+        case "open_mini_app":
+          handlers.open_mini_app(String(p.target ?? ""));
+          break;
+        case "view_cast":
+          handlers.view_cast({ hash: String(p.hash ?? "") });
+          break;
+        case "view_profile":
+          handlers.view_profile({ fid: Number(p.fid ?? 0) });
+          break;
+        case "compose_cast":
+          handlers.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":
+          handlers.view_token({ token: String(p.token ?? "") });
+          break;
+        case "send_token":
+          handlers.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":
+          handlers.swap_token({
+            sellToken: p.sellToken ? String(p.sellToken) : undefined,
+            buyToken: p.buyToken ? String(p.buyToken) : undefined,
+          });
+          break;
+        default:
+          break;
+      }
+    },
+    [handlers],
+  );
+
+  return (
+    <div style={{ position: "relative", width: "100%" }}>
+      {showConfetti && <ConfettiOverlay />}
+      {loading && (
+        <div
+          style={{
+            position: "absolute",
+            inset: 0,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            zIndex: 10,
+            fontSize: 14,
+            color: "var(--text-muted)",
+            background: "var(--bg-primary, rgba(0,0,0,0.6))",
+            backdropFilter: "blur(4px)",
+          }}
+        >
+          Loading...
+        </div>
+      )}
+
+      <div style={previewSurfaceStyle}>
+        <SnapPreviewAccentProvider pageAccent={snap.theme?.accent}>
+          <SnapCatalogView
+            key={pageKey}
+            spec={spec}
+            state={initialState}
+            loading={false}
+            onStateChange={(changes) => {
+              applyStatePaths(stateRef.current, changes);
+            }}
+            onAction={handleAction}
+          />
+        </SnapPreviewAccentProvider>
+      </div>
+    </div>
+  );
+}

package/src/react/lib/preview-primary-css.ts

@@ -0,0 +1,57 @@
+import type { CSSProperties } from "react";
+import { resolveSnapPaletteHex } from "./resolve-palette-hex";
+
+/** Readable on-primary text for hex backgrounds (e.g. amber vs purple). */
+function pickForegroundForBg(hex: string): string {
+  const h = hex.replace(/^#/, "");
+  if (h.length !== 6) return "#ffffff";
+  const r = Number.parseInt(h.slice(0, 2), 16);
+  const g = Number.parseInt(h.slice(2, 4), 16);
+  const b = Number.parseInt(h.slice(4, 6), 16);
+  const yiq = (r * 299 + g * 587 + b * 114) / 1000;
+  return yiq >= 180 ? "#0a0a0a" : "#ffffff";
+}
+
+/** Match `globals.css` `--snap-card-bg` so hover tints sit on the preview card. */
+const SNAP_CARD_BG: Record<"light" | "dark", string> = {
+  light: "#ffffff",
+  dark: "#23262f",
+};
+
+function snapActionPrimaryHover(
+  hex: string,
+  appearance: "light" | "dark",
+): string {
+  return appearance === "light"
+    ? `color-mix(in srgb, ${hex} 82%, #000000)`
+    : `color-mix(in srgb, ${hex} 78%, #ffffff)`;
+}
+
+function snapActionOutlineHover(
+  hex: string,
+  appearance: "light" | "dark",
+): string {
+  const card = SNAP_CARD_BG[appearance];
+  return `color-mix(in srgb, ${hex} 14%, ${card})`;
+}
+
+/**
+ * Overrides Neynar / Tailwind theme tokens so `bg-primary`, `border-primary`, etc.
+ * use the snap spec accent inside the preview subtree.
+ */
+export function snapPreviewPrimaryCssProperties(
+  accentName: string,
+  appearance: "light" | "dark",
+): CSSProperties {
+  const hex = resolveSnapPaletteHex(accentName, appearance);
+  const fg = pickForegroundForBg(hex);
+  return {
+    "--primary": hex,
+    "--primary-foreground": fg,
+    "--ring": hex,
+    "--color-primary": hex,
+    "--color-primary-foreground": fg,
+    "--snap-action-primary-hover": snapActionPrimaryHover(hex, appearance),
+    "--snap-action-outline-hover": snapActionOutlineHover(hex, appearance),
+  } as CSSProperties;
+}

package/src/react/lib/resolve-palette-hex.ts

@@ -0,0 +1,20 @@
+import {
+  PALETTE_DARK_HEX,
+  PALETTE_LIGHT_HEX,
+  type PaletteColor,
+} from "@farcaster/snap";
+
+/** Resolve a snap palette color name to hex for the current shell appearance. */
+export function resolveSnapPaletteHex(
+  name: string,
+  appearance: "light" | "dark",
+): string {
+  const map = appearance === "dark" ? PALETTE_DARK_HEX : PALETTE_LIGHT_HEX;
+  if (
+    Object.hasOwn(map, name) &&
+    typeof map[name as PaletteColor] === "string"
+  ) {
+    return map[name as PaletteColor];
+  }
+  return map.purple;
+}

package/src/react-native/catalog-renderer.tsx

@@ -0,0 +1,37 @@
+import { createRenderer } from "@json-render/react-native";
+import { snapJsonRenderCatalog } from "@farcaster/snap/ui";
+import { SnapActionButton } from "./components/snap-action-button";
+import { SnapBadge } from "./components/snap-badge";
+import { SnapIcon } from "./components/snap-icon";
+import { SnapImage } from "./components/snap-image";
+import { SnapInput } from "./components/snap-input";
+import { SnapItem } from "./components/snap-item";
+import { SnapItemGroup } from "./components/snap-item-group";
+import { SnapProgress } from "./components/snap-progress";
+import { SnapSeparator } from "./components/snap-separator";
+import { SnapSlider } from "./components/snap-slider";
+import { SnapStack } from "./components/snap-stack";
+import { SnapSwitch } from "./components/snap-switch";
+import { SnapText } from "./components/snap-text";
+import { SnapToggleGroup } from "./components/snap-toggle-group";
+
+/**
+ * Maps snap json-render catalog types to React Native primitives.
+ * Keys match the snap wire-format `type` strings exactly (snake_case).
+ */
+export const SnapCatalogView = createRenderer(snapJsonRenderCatalog, {
+  badge: SnapBadge,
+  button: SnapActionButton,
+  icon: SnapIcon,
+  image: SnapImage,
+  input: SnapInput,
+  item: SnapItem,
+  item_group: SnapItemGroup,
+  progress: SnapProgress,
+  separator: SnapSeparator,
+  slider: SnapSlider,
+  stack: SnapStack,
+  switch: SnapSwitch,
+  text: SnapText,
+  toggle_group: SnapToggleGroup,
+});

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

@@ -0,0 +1,92 @@
+declare const __DEV__: boolean;
+
+import type { ComponentRenderProps } from "@json-render/react-native";
+import { Pressable, StyleSheet, Text, View } from "react-native";
+import { useSnapPalette } from "../use-snap-palette";
+import { useSnapTheme } from "../theme";
+import { ICON_MAP } from "./snap-icon";
+
+const VARIANT_MAP: Record<string, "default" | "secondary" | "outline" | "ghost"> = {
+  default: "default",
+  secondary: "secondary",
+  outline: "outline",
+  ghost: "ghost",
+};
+
+export function SnapActionButton({
+  element: { props },
+  emit,
+}: ComponentRenderProps<Record<string, unknown>>) {
+  const { accentHex } = useSnapPalette();
+  const { colors } = useSnapTheme();
+  const label = String(props.label ?? "Action");
+  const variant = VARIANT_MAP[String(props.variant ?? "default")] ?? "default";
+  const iconName = props.icon ? String(props.icon) : undefined;
+
+  const variantStyle = (() => {
+    switch (variant) {
+      case "default":
+        return { backgroundColor: accentHex };
+      case "secondary":
+        return { backgroundColor: "transparent", borderWidth: 1.5, borderColor: accentHex };
+      case "outline":
+        return { backgroundColor: "rgba(255,255,255,0.04)", borderWidth: 1, borderColor: colors.border };
+      case "ghost":
+        return { backgroundColor: "transparent" };
+    }
+  })();
+
+  const textColor = variant === "default" ? "#fff" : variant === "secondary" ? accentHex : colors.text;
+  const iconColor = variant === "default" ? "#fff" : variant === "secondary" ? accentHex : colors.text;
+
+  return (
+    <View style={styles.outer}>
+      <Pressable
+        style={({ pressed }) => [
+          styles.btn,
+          variant === "default" ? styles.btnDefault : styles.btnOther,
+          variantStyle,
+          pressed && styles.pressed,
+        ]}
+        onPress={() => {
+          void (async () => {
+            try {
+              await emit("press");
+            } catch (err: unknown) {
+              if (typeof __DEV__ !== "undefined" && __DEV__) {
+                // eslint-disable-next-line no-console
+                console.error("[snap] action failed", err);
+              }
+            }
+          })();
+        }}
+      >
+        {iconName && ICON_MAP[iconName] ? (
+          (() => { const I = ICON_MAP[iconName]!; return <I size={16} color={iconColor} />; })()
+        ) : null}
+        <Text style={{ color: textColor, fontSize: 14, fontWeight: "600" }}>
+          {label}
+        </Text>
+      </Pressable>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  outer: { flex: 1, minWidth: 0 },
+  btn: {
+    paddingHorizontal: 16,
+    borderRadius: 10,
+    alignItems: "center",
+    justifyContent: "center",
+    flexDirection: "row",
+    gap: 8,
+  },
+  btnDefault: {
+    paddingVertical: 10,
+  },
+  btnOther: {
+    paddingVertical: 8,
+  },
+  pressed: { opacity: 0.88 },
+});

package/src/react-native/components/snap-badge.tsx

@@ -0,0 +1,57 @@
+import type { ComponentRenderProps } from "@json-render/react-native";
+import { StyleSheet, Text, View } from "react-native";
+import { useSnapPalette } from "../use-snap-palette";
+import { ICON_MAP } from "./snap-icon";
+
+export function SnapBadge({
+  element: { props },
+}: ComponentRenderProps<Record<string, unknown>>) {
+  const { accentHex, hex } = useSnapPalette();
+  const label = String(props.label ?? "");
+  const color = props.color ? String(props.color) : undefined;
+  const iconName = props.icon ? String(props.icon) : undefined;
+  const isAccent = !color || color === "accent";
+  const resolvedColor = isAccent ? accentHex : hex(color);
+
+  const Icon = iconName ? ICON_MAP[iconName] : undefined;
+
+  return (
+    <View
+      style={[
+        styles.badge,
+        isAccent
+          ? { backgroundColor: resolvedColor, borderColor: resolvedColor }
+          : { borderColor: resolvedColor },
+      ]}
+    >
+      {Icon && (
+        <Icon size={12} color={isAccent ? "#fff" : resolvedColor} />
+      )}
+      <Text
+        style={[
+          styles.label,
+          { color: isAccent ? "#fff" : resolvedColor },
+        ]}
+      >
+        {label}
+      </Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  badge: {
+    alignSelf: "flex-start",
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 4,
+    paddingHorizontal: 8,
+    paddingVertical: 2,
+    borderRadius: 9999,
+    borderWidth: 1,
+  },
+  label: {
+    fontSize: 12,
+    fontWeight: "500",
+  },
+});

package/src/react-native/components/snap-icon.tsx

@@ -0,0 +1,102 @@
+import type { ComponentRenderProps } from "@json-render/react-native";
+import { View } from "react-native";
+import { useSnapPalette } from "../use-snap-palette";
+import {
+  ArrowRight,
+  ArrowLeft,
+  ExternalLink,
+  ChevronRight,
+  Check,
+  X,
+  AlertTriangle,
+  Info,
+  Clock,
+  Heart,
+  MessageCircle,
+  Repeat,
+  Share,
+  User,
+  Users,
+  Star,
+  Trophy,
+  Zap,
+  Flame,
+  Gift,
+  ImageIcon,
+  Play,
+  Pause,
+  Wallet,
+  Coins,
+  Plus,
+  Minus,
+  RefreshCw,
+  Bookmark,
+  ThumbsUp,
+  ThumbsDown,
+  TrendingUp,
+  TrendingDown,
+  type LucideIcon,
+} from "lucide-react-native";
+
+const ICON_MAP: Record<string, LucideIcon> = {
+  "arrow-right": ArrowRight,
+  "arrow-left": ArrowLeft,
+  "external-link": ExternalLink,
+  "chevron-right": ChevronRight,
+  check: Check,
+  x: X,
+  "alert-triangle": AlertTriangle,
+  info: Info,
+  clock: Clock,
+  heart: Heart,
+  "message-circle": MessageCircle,
+  repeat: Repeat,
+  share: Share,
+  user: User,
+  users: Users,
+  star: Star,
+  trophy: Trophy,
+  zap: Zap,
+  flame: Flame,
+  gift: Gift,
+  image: ImageIcon,
+  play: Play,
+  pause: Pause,
+  wallet: Wallet,
+  coins: Coins,
+  plus: Plus,
+  minus: Minus,
+  "refresh-cw": RefreshCw,
+  bookmark: Bookmark,
+  "thumbs-up": ThumbsUp,
+  "thumbs-down": ThumbsDown,
+  "trending-up": TrendingUp,
+  "trending-down": TrendingDown,
+};
+
+const SIZE_PX: Record<string, number> = {
+  sm: 16,
+  md: 20,
+};
+
+export function SnapIcon({
+  element: { props },
+}: ComponentRenderProps<Record<string, unknown>>) {
+  const { accentHex, hex } = useSnapPalette();
+  const name = String(props.name ?? "info");
+  const size = SIZE_PX[String(props.size ?? "md")] ?? 20;
+  const color = props.color ? String(props.color) : undefined;
+  const isAccent = !color || color === "accent";
+  const resolvedColor = isAccent ? accentHex : hex(color);
+
+  const Icon = ICON_MAP[name];
+  if (!Icon) return null;
+
+  return (
+    <View style={{ alignItems: "center", justifyContent: "center" }}>
+      <Icon size={size} color={resolvedColor} />
+    </View>
+  );
+}
+
+export { ICON_MAP };