@farcaster/snap 2.0.0 → 2.0.1

package/src/react-native/index.tsx

@@ -0,0 +1,83 @@
+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 { SnapCardV1 } from "./v1/snap-view";
+import { SnapCardV2 } from "./v2/snap-view";
+
+// ─── Public types ──────────────────────────────────────
+
+export type { JsonValue, SnapPage, SnapActionHandlers } from "./types";
+
+// ─── Re-exports ───────────────────────────────────────
+
+export { useSnapTheme, hexToRgba };
+export type { SnapNativeColors };
+
+// ─── SnapCard (version-switching) ─────────────────────
+
+export function SnapCard({
+  snap,
+  handlers,
+  loading = false,
+  appearance = "dark",
+  colors,
+  borderRadius = 16,
+  showOverflowWarning = false,
+  onValidationError,
+  validationErrorFallback,
+  actionError,
+  plain = false,
+}: {
+  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;
+  /** Server-side action error message to display inline. */
+  actionError?: string | null;
+  /** When true, renders without card frame (no border, background, or padding). */
+  plain?: boolean;
+}) {
+  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}
+        actionError={actionError}
+        plain={plain}
+      />
+    );
+  }
+
+  return (
+    <SnapCardV1
+      snap={snap}
+      handlers={handlers}
+      loading={loading}
+      appearance={appearance}
+      colors={colors}
+      borderRadius={borderRadius}
+      actionError={actionError}
+      plain={plain}
+    />
+  );
+}

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/theme.tsx

@@ -0,0 +1,85 @@
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+
+// ─── Color tokens ─────────────────────────────────────
+
+export type SnapNativeColors = {
+  bg: string;
+  surface: string;
+  text: string;
+  textSecondary: string;
+  border: string;
+  inputBg: string;
+  muted: string;
+  /** Subtle tint for toggle button resting state */
+  mutedSubtle: string;
+  /** Slightly stronger tint for hover/press state */
+  mutedHover: string;
+  /** Stronger tint for selected state (toggle group) */
+  mutedSelected: string;
+};
+
+const DEFAULT_LIGHT: SnapNativeColors = {
+  bg: "#dfe3e8",
+  surface: "#ffffff",
+  text: "rgba(0,0,0,0.9)",
+  textSecondary: "rgba(0,0,0,0.5)",
+  border: "rgba(0,0,0,0.1)",
+  inputBg: "rgba(0,0,0,0.06)",
+  muted: "rgba(0,0,0,0.08)",
+  mutedSubtle: "rgba(0,0,0,0.04)",
+  mutedHover: "rgba(0,0,0,0.12)",
+  mutedSelected: "rgba(0,0,0,0.16)",
+};
+
+const DEFAULT_DARK: SnapNativeColors = {
+  bg: "#111318",
+  surface: "#1a1d24",
+  text: "rgba(255,255,255,0.9)",
+  textSecondary: "rgba(255,255,255,0.5)",
+  border: "rgba(255,255,255,0.1)",
+  inputBg: "rgba(255,255,255,0.04)",
+  muted: "rgba(255,255,255,0.06)",
+  mutedSubtle: "rgba(255,255,255,0.03)",
+  mutedHover: "rgba(255,255,255,0.08)",
+  mutedSelected: "rgba(255,255,255,0.12)",
+};
+
+// ─── Context ──────────────────────────────────────────
+
+interface SnapThemeValue {
+  mode: "light" | "dark";
+  colors: SnapNativeColors;
+}
+
+const SnapThemeContext = createContext<SnapThemeValue>({
+  mode: "dark",
+  colors: DEFAULT_DARK,
+});
+
+export function SnapThemeProvider({
+  appearance,
+  colors,
+  children,
+}: {
+  appearance: "light" | "dark";
+  colors?: Partial<SnapNativeColors>;
+  children: ReactNode;
+}) {
+  const value = useMemo<SnapThemeValue>(() => {
+    const defaults = appearance === "dark" ? DEFAULT_DARK : DEFAULT_LIGHT;
+    return {
+      mode: appearance,
+      colors: colors ? { ...defaults, ...colors } : defaults,
+    };
+  }, [appearance, colors]);
+
+  return (
+    <SnapThemeContext.Provider value={value}>
+      {children}
+    </SnapThemeContext.Provider>
+  );
+}
+
+export function useSnapTheme(): SnapThemeValue {
+  return useContext(SnapThemeContext);
+}

package/src/react-native/types.ts

@@ -0,0 +1,38 @@
+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_snap: (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/use-snap-palette.ts

@@ -0,0 +1,64 @@
+import {
+  DEFAULT_THEME_ACCENT,
+  PALETTE_COLOR_VALUES,
+  PALETTE_LIGHT_HEX,
+  PALETTE_DARK_HEX,
+  type PaletteColor,
+} from "@farcaster/snap";
+import { useStateStore } from "@json-render/react-native";
+import { useSnapTheme } from "./theme";
+
+function resolveHex(name: string, appearance: "light" | "dark"): string {
+  const map = appearance === "dark" ? PALETTE_DARK_HEX : PALETTE_LIGHT_HEX;
+  if (Object.hasOwn(map, name)) {
+    return map[name as PaletteColor];
+  }
+  return map.purple;
+}
+
+function isPaletteColor(s: string): s is PaletteColor {
+  return (PALETTE_COLOR_VALUES as readonly string[]).includes(s);
+}
+
+function themeAccentFromStore(get: (path: string) => unknown): PaletteColor {
+  const raw = get("/theme/accent");
+  if (typeof raw === "string" && isPaletteColor(raw)) {
+    return raw;
+  }
+  return DEFAULT_THEME_ACCENT;
+}
+
+export function useSnapPalette() {
+  const { mode } = useSnapTheme();
+  const { get } = useStateStore();
+  const accentName = themeAccentFromStore(get);
+  const accentHex = resolveHex(accentName, mode);
+
+  const hex = (semantic: string) =>
+    semantic === "accent" ? accentHex : resolveHex(semantic, mode);
+
+  return { appearance: mode, accentName, accentHex, hex };
+}
+
+/** `#RRGGBB` + alpha → `rgba(...)` for React Native styles. */
+export function hexToRgba(hex: string, alpha: number): string {
+  const m = /^#([0-9a-fA-F]{6})$/.exec(hex.trim());
+  if (!m) {
+    return `rgba(0,0,0,${alpha})`;
+  }
+  const n = Number.parseInt(m[1]!, 16);
+  const r = (n >> 16) & 255;
+  const g = (n >> 8) & 255;
+  const b = n & 255;
+  return `rgba(${r},${g},${b},${alpha})`;
+}
+
+export function useSnapPreviewChromePalette(themeAccent: string | undefined) {
+  const { mode } = useSnapTheme();
+  const accentName =
+    typeof themeAccent === "string" && isPaletteColor(themeAccent)
+      ? themeAccent
+      : DEFAULT_THEME_ACCENT;
+  const accentHex = resolveHex(accentName, mode);
+  return { appearance: mode, accentName, accentHex };
+}

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

@@ -0,0 +1,229 @@
+import { useEffect, useState } from "react";
+import { View, Text, StyleSheet, Pressable } from "react-native";
+import { SnapThemeProvider, useSnapTheme, type SnapNativeColors } from "../theme";
+import { SnapViewCoreInner } from "../snap-view-core";
+import type { SnapPage, SnapActionHandlers } from "../types";
+
+const SNAP_MAX_HEIGHT = 500;
+
+// ─── SnapViewV1 (no validation) ──────────────────────
+
+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 with expandable clipping) ──
+
+function SnapCardV1Inner({
+  snap,
+  handlers,
+  loading = false,
+  borderRadius,
+  actionError,
+  appearance,
+  plain,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  borderRadius: number;
+  actionError?: string | null;
+  appearance: "light" | "dark";
+  plain: boolean;
+}) {
+  const { colors } = useSnapTheme();
+  const [contentHeight, setContentHeight] = useState(0);
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  useEffect(() => {
+    setIsExpanded(false);
+    setContentHeight(0);
+  }, [snap]);
+
+  const isExpandable = contentHeight > SNAP_MAX_HEIGHT + 1;
+  const isClipped = isExpandable && !isExpanded;
+
+  return (
+    <>
+      <View style={cardStyles.frameRing}>
+        <View
+          style={[
+            plain ? undefined : cardStyles.card,
+            plain ? undefined : {
+              borderRadius,
+              borderColor: colors.border,
+              backgroundColor: colors.surface,
+            },
+          ]}
+        >
+          <View
+            style={isClipped ? { maxHeight: SNAP_MAX_HEIGHT, overflow: "hidden" } : undefined}
+          >
+            <View
+              collapsable={false}
+              onLayout={(event) => {
+                const nextHeight = Math.round(event.nativeEvent.layout.height);
+                setContentHeight((currentHeight) =>
+                  isClipped
+                    ? Math.max(currentHeight, nextHeight)
+                    : currentHeight === nextHeight
+                      ? currentHeight
+                      : nextHeight,
+                );
+              }}
+              style={plain ? undefined : cardStyles.body}
+            >
+              <SnapViewV1Inner
+                snap={snap}
+                handlers={handlers}
+                loading={loading}
+              />
+            </View>
+          </View>
+          {isExpandable ? (
+            <View
+              style={[
+                cardStyles.expandRow,
+                plain
+                  ? cardStyles.expandRowPlain
+                  : { borderTopColor: colors.border },
+              ]}
+            >
+              <Pressable
+                style={({ pressed }) => [
+                  cardStyles.expandButton,
+                  {
+                    backgroundColor: pressed
+                      ? colors.mutedHover
+                      : colors.muted,
+                  },
+                ]}
+                onPress={() => {
+                  setIsExpanded((value) => !value);
+                }}
+              >
+                <Text
+                  style={[cardStyles.expandButtonText, { color: colors.text }]}
+                >
+                  {isExpanded ? "Show less" : "Show more"}
+                </Text>
+              </Pressable>
+            </View>
+          ) : null}
+        </View>
+      </View>
+      {actionError && (
+        <Text
+          style={[
+            cardStyles.actionError,
+            {
+              color:
+                appearance === "dark"
+                  ? "rgba(255,100,100,0.9)"
+                  : "rgba(200,0,0,0.8)",
+            },
+          ]}
+        >
+          {actionError}
+        </Text>
+      )}
+    </>
+  );
+}
+
+export function SnapCardV1({
+  snap,
+  handlers,
+  loading = false,
+  appearance = "dark",
+  colors,
+  borderRadius = 16,
+  actionError,
+  plain = false,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  appearance?: "light" | "dark";
+  colors?: Partial<SnapNativeColors>;
+  borderRadius?: number;
+  actionError?: string | null;
+  plain?: boolean;
+}) {
+  return (
+    <SnapThemeProvider appearance={appearance} colors={colors}>
+      <SnapCardV1Inner
+        snap={snap}
+        handlers={handlers}
+        loading={loading}
+        borderRadius={borderRadius}
+        actionError={actionError}
+        appearance={appearance}
+        plain={plain}
+      />
+    </SnapThemeProvider>
+  );
+}
+
+const cardStyles = StyleSheet.create({
+  frameRing: { alignSelf: "stretch" },
+  card: { overflow: "hidden", borderWidth: 1, minHeight: 120 },
+  body: { paddingHorizontal: 16, paddingVertical: 16 },
+  expandRow: {
+    alignItems: "center",
+    paddingHorizontal: 16,
+    paddingTop: 10,
+    paddingBottom: 12,
+    borderTopWidth: StyleSheet.hairlineWidth,
+  },
+  expandRowPlain: {
+    paddingHorizontal: 0,
+    paddingTop: 8,
+    paddingBottom: 0,
+    borderTopWidth: 0,
+  },
+  expandButton: {
+    minWidth: 92,
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 9999,
+    paddingHorizontal: 10,
+    paddingVertical: 6,
+  },
+  expandButtonText: {
+    fontSize: 13,
+    lineHeight: 18,
+    fontWeight: "600",
+  },
+  actionError: { paddingHorizontal: 12, paddingVertical: 8, fontSize: 13 },
+});