@farcaster/snap 2.0.0 → 2.0.2

package/src/react/components/switch.tsx

@@ -2,32 +2,29 @@
 
 import { useId } from "react";
 import { useStateStore } from "@json-render/react";
-import { Label } from "@neynar/ui/label";
 import { Switch } from "@neynar/ui/switch";
-import { useColorMode } from "@neynar/ui/color-mode";
-import { cn } from "@neynar/ui/utils";
-import { useSnapAccentScopeStyle } from "../hooks/use-snap-accent";
+import { Label } from "@neynar/ui/label";
+import { useSnapColors } from "../hooks/use-snap-colors";
 
 export function SnapSwitch({
   element: { props },
 }: {
   element: { props: Record<string, unknown> };
 }) {
-  const id = useId();
   const { get, set } = useStateStore();
-  const { mode } = useColorMode();
-  const accentStyle = useSnapAccentScopeStyle();
+  const colors = useSnapColors();
   const name = String(props.name ?? "switch");
-  const path = `/inputs/${name}`;
   const label = props.label ? String(props.label) : undefined;
-  const fallback = Boolean(props.defaultChecked ?? false);
+  const path = `/inputs/${name}`;
   const raw = get(path);
-  const checked = raw === undefined || raw === null ? fallback : Boolean(raw);
+  const checked =
+    raw !== undefined ? Boolean(raw) : Boolean(props.defaultChecked);
+  const id = useId();
 
   return (
     <div className="flex items-center justify-between gap-3">
       {label && (
-        <Label htmlFor={id} className="text-foreground font-normal">
+        <Label htmlFor={id} className="font-normal" style={{ color: colors.text }}>
           {label}
         </Label>
       )}
@@ -35,11 +32,10 @@ export function SnapSwitch({
         id={id}
         checked={checked}
         onCheckedChange={(v) => set(path, v)}
-        style={accentStyle}
-        className={cn(
-          mode === "light" &&
-            "data-unchecked:!bg-border data-unchecked:!border-(--input-border)",
-        )}
+        style={{
+          backgroundColor: checked ? colors.accent : colors.muted,
+          borderColor: checked ? colors.accent : colors.inputBorder,
+        }}
       />
     </div>
   );

package/src/react/components/text.tsx

@@ -1,17 +1,11 @@
 "use client";
 
-import { Text, Title } from "@neynar/ui/typography";
+import { Text } from "@neynar/ui/typography";
+import { useSnapColors } from "../hooks/use-snap-colors";
 
 const SIZE_MAP = {
-  lg: { component: "title", textSize: undefined, order: 3 },
-  md: { component: "text", textSize: "base" as const, order: undefined },
-  sm: { component: "text", textSize: "sm" as const, order: undefined },
-} as const;
-
-const WEIGHT_MAP = {
-  bold: "bold",
-  medium: "medium",
-  normal: "normal",
+  md: { textSize: "base" as const },
+  sm: { textSize: "sm" as const },
 } as const;
 
 export function SnapText({
@@ -20,23 +14,20 @@ export function SnapText({
   element: { props: Record<string, unknown> };
 }) {
   const content = String(props.content ?? "");
-  const size = String(props.size ?? "md") as "lg" | "md" | "sm";
-  const weight = props.weight ? String(props.weight) as "bold" | "medium" | "normal" : undefined;
+  const size = String(props.size ?? "md") as "md" | "sm";
+  const weight = props.weight ? String(props.weight) as "bold" | "normal" : undefined;
   const align = (props.align as "left" | "center" | "right") ?? undefined;
   const config = SIZE_MAP[size] ?? SIZE_MAP.md;
-
-  const alignClass = align === "center" ? "text-center" : align === "right" ? "text-right" : "";
-
-  if (config.component === "title") {
-    return (
-      <Title order={config.order} weight={weight ?? "bold"} className={`flex-1 ${alignClass}`}>
-        {content}
-      </Title>
-    );
-  }
+  const colors = useSnapColors();
 
   return (
-    <Text size={config.textSize} weight={weight} align={align} className="flex-1">
+    <Text
+      size={config.textSize}
+      weight={weight}
+      align={align}
+      className="flex-1"
+      style={{ color: colors.text }}
+    >
       {content}
     </Text>
   );

package/src/react/components/toggle-group.tsx

@@ -1,9 +1,10 @@
 "use client";
 
+import { useState } from "react";
 import { useStateStore } from "@json-render/react";
 import { Label } from "@neynar/ui/label";
 import { cn } from "@neynar/ui/utils";
-import { useSnapAccentScopeStyle } from "../hooks/use-snap-accent";
+import { useSnapColors } from "../hooks/use-snap-colors";
 
 export function SnapToggleGroup({
   element: { props },
@@ -11,7 +12,7 @@ export function SnapToggleGroup({
   element: { props: Record<string, unknown> };
 }) {
   const { get, set } = useStateStore();
-  const accentStyle = useSnapAccentScopeStyle();
+  const colors = useSnapColors();
   const name = String(props.name ?? "toggle_group");
   const path = `/inputs/${name}`;
   const label = props.label ? String(props.label) : undefined;
@@ -50,30 +51,46 @@ export function SnapToggleGroup({
   };
 
   const isVertical = orientation === "vertical";
+  const [hoveredIdx, setHoveredIdx] = useState<number | null>(null);
 
   return (
-    <div className="w-full space-y-1.5" style={accentStyle}>
-      {label && <Label>{label}</Label>}
+    <div className="w-full space-y-1.5">
+      {label && <Label style={{ color: colors.text }}>{label}</Label>}
       <div
         className={cn(
-          "flex gap-1 rounded-lg bg-border/20 p-1",
+          "flex gap-1 rounded-lg p-1",
           isVertical ? "flex-col" : "flex-row",
         )}
+        style={{ backgroundColor: colors.muted }}
       >
-        {options.map((opt) => {
+        {options.map((opt, i) => {
           const isSelected = selected.includes(opt);
+          const isHovered = hoveredIdx === i && !isSelected;
           return (
             <button
               key={opt}
               type="button"
               onClick={() => toggle(opt)}
+              onPointerEnter={() => setHoveredIdx(i)}
+              onPointerLeave={() => setHoveredIdx(null)}
               className={cn(
                 "rounded-md px-3 py-2 text-sm font-medium transition-colors",
                 isVertical ? "w-full" : "flex-1",
-                isSelected
-                  ? "bg-primary text-primary-foreground"
-                  : "text-foreground hover:bg-border/30",
               )}
+              style={{
+                transition: "background-color 0.15s, color 0.15s",
+                ...(isSelected
+                  ? {
+                      backgroundColor: colors.mode === "dark" ? "rgba(255,255,255,0.10)" : "rgba(0,0,0,0.08)",
+                      color: colors.text,
+                    }
+                  : {
+                      color: colors.text,
+                      backgroundColor: isHovered
+                        ? (colors.mode === "dark" ? "rgba(255,255,255,0.04)" : "rgba(0,0,0,0.04)")
+                        : (colors.mode === "dark" ? "rgba(255,255,255,0.02)" : "rgba(0,0,0,0.02)"),
+                    }),
+              }}
             >
               {opt}
             </button>

package/src/react/hooks/use-snap-colors.ts

@@ -0,0 +1,128 @@
+"use client";
+
+import { useMemo } from "react";
+import { useStateStore } from "@json-render/react";
+import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex";
+import { useSnapPreviewPageAccent, useSnapAppearance } from "../accent-context";
+import type { PaletteColor } from "@farcaster/snap";
+import { PALETTE_DARK_HEX, PALETTE_LIGHT_HEX } from "@farcaster/snap";
+
+/** Readable foreground color (black or white) for a given hex background. */
+export 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";
+}
+
+const NEUTRAL_LIGHT = {
+  text: "#111111",
+  textMuted: "#6B7280",
+  border: "#E5E7EB",
+  muted: "rgba(0,0,0,0.06)",
+  surface: "#ffffff",
+  inputBorder: "#E5E7EB",
+  inputBg: "rgba(0,0,0,0.06)",
+} as const;
+
+const NEUTRAL_DARK = {
+  text: "#FAFAFA",
+  textMuted: "#A1A1AA",
+  border: "#2D2D44",
+  muted: "rgba(255,255,255,0.03)",
+  surface: "#23262f",
+  inputBorder: "#3F3F46",
+  inputBg: "rgba(255,255,255,0.03)",
+} as const;
+
+export type SnapColors = {
+  /** Resolved accent hex */
+  accent: string;
+  /** Readable foreground for accent bg (black or white) */
+  accentFg: string;
+  /** Primary button hover color */
+  accentHover: string;
+  /** Secondary/outline button hover color */
+  outlineHover: string;
+  /** Primary text color */
+  text: string;
+  /** Muted/secondary text color */
+  textMuted: string;
+  /** Border color */
+  border: string;
+  /** Muted background (tracks, containers) */
+  muted: string;
+  /** Surface/card background */
+  surface: string;
+  /** Input border */
+  inputBorder: string;
+  /** Input background */
+  inputBg: string;
+  /** Current color mode */
+  mode: "light" | "dark";
+  /** Resolve a palette color name to hex */
+  paletteHex: (name: string) => string;
+  /** Resolve a palette color name to hex, with accent fallback */
+  colorHex: (name: string | undefined) => string;
+};
+
+function buildSnapColors(
+  accentName: string,
+  mode: "light" | "dark",
+): SnapColors {
+  const accent = resolveSnapPaletteHex(accentName, mode);
+  const accentFg = pickForegroundForBg(accent);
+  const neutrals = mode === "dark" ? NEUTRAL_DARK : NEUTRAL_LIGHT;
+  const paletteMap = mode === "dark" ? PALETTE_DARK_HEX : PALETTE_LIGHT_HEX;
+
+  const accentHover =
+    mode === "light"
+      ? `color-mix(in srgb, ${accent} 82%, #000000)`
+      : `color-mix(in srgb, ${accent} 78%, #ffffff)`;
+
+  const outlineHover = `color-mix(in srgb, ${accent} 14%, ${neutrals.surface})`;
+
+  const paletteHex = (name: string) => resolveSnapPaletteHex(name, mode);
+
+  const colorHex = (name: string | undefined) => {
+    if (!name || name === "accent") return accent;
+    if (Object.hasOwn(paletteMap, name)) return paletteMap[name as PaletteColor];
+    return accent;
+  };
+
+  return {
+    accent,
+    accentFg,
+    accentHover,
+    outlineHover,
+    ...neutrals,
+    mode,
+    paletteHex,
+    colorHex,
+  };
+}
+
+/**
+ * Returns fully resolved color values for snap components.
+ * All colors are concrete hex values (or color-mix expressions for hover states)
+ * so they can be used as inline styles, independent of host app CSS.
+ */
+export function useSnapColors(): SnapColors {
+  const { get } = useStateStore();
+  const mode = useSnapAppearance();
+  const pageAccent = useSnapPreviewPageAccent();
+  const fromState = get("/theme/accent");
+  const accentRaw =
+    (typeof pageAccent === "string" && pageAccent.length > 0
+      ? pageAccent
+      : fromState) ?? undefined;
+  const accentName =
+    typeof accentRaw === "string" && accentRaw.length > 0
+      ? accentRaw
+      : "purple";
+
+  return useMemo(() => buildSnapColors(accentName, mode), [accentName, mode]);
+}

package/src/react/index.tsx

@@ -1,19 +1,11 @@
 "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";
+import type { ReactNode } from "react";
+import type { ValidationResult } from "../validator.js";
+import { SPEC_VERSION_2 } from "../constants";
+import { SnapCardV1 } from "./v1/snap-view";
+import { SnapCardV2 } from "./v2/snap-view";
 
 // ─── Public types ──────────────────────────────────────
 
@@ -35,6 +27,7 @@ export type SnapPage = {
 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;
@@ -50,272 +43,63 @@ export type SnapActionHandlers = {
     recipientFid?: number;
     recipientAddress?: string;
   }) => void;
-  swap_token: (params: {
-    sellToken?: string;
-    buyToken?: 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;
+// ─── SnapCard ────────────────────────────────────────
 
-// ─── SnapView ──────────────────────────────────────────
-
-export function SnapView({
+export function SnapCard({
   snap,
   handlers,
   loading = false,
   appearance = "dark",
+  maxWidth = 480,
+  showOverflowWarning = false,
+  onValidationError,
+  validationErrorFallback,
+  actionError,
+  plain = false,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
   loading?: boolean;
   appearance?: "light" | "dark";
+  maxWidth?: number;
+  /** When true, extends to 700px and shows a warning overlay below 500px. When false, clips at 500px. Only applies to v2 snaps. */
+  showOverflowWarning?: boolean;
+  onValidationError?: (result: ValidationResult) => void;
+  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;
 }) {
-  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],
-  );
+  if (snap.version === SPEC_VERSION_2) {
+    return (
+      <SnapCardV2
+        snap={snap}
+        handlers={handlers}
+        loading={loading}
+        appearance={appearance}
+        maxWidth={maxWidth}
+        showOverflowWarning={showOverflowWarning}
+        onValidationError={onValidationError}
+        validationErrorFallback={validationErrorFallback}
+        actionError={actionError}
+        plain={plain}
+      />
+    );
+  }
 
   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>
+    <SnapCardV1
+      snap={snap}
+      handlers={handlers}
+      loading={loading}
+      appearance={appearance}
+      maxWidth={maxWidth}
+      actionError={actionError}
+      plain={plain}
+    />
   );
 }