@farcaster/snap 2.0.0 → 2.0.2

package/dist/react/components/switch.js

@@ -2,22 +2,20 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 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.js";
+import { Label } from "@neynar/ui/label";
+import { useSnapColors } from "../hooks/use-snap-colors.js";
 export function SnapSwitch({ element: { props }, }) {
-    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);
-    return (_jsxs("div", { className: "flex items-center justify-between gap-3", children: [label && (_jsx(Label, { htmlFor: id, className: "text-foreground font-normal", children: label })), _jsx(Switch, { id: id, checked: checked, onCheckedChange: (v) => set(path, v), style: accentStyle, className: cn(mode === "light" &&
-                    "data-unchecked:!bg-border data-unchecked:!border-(--input-border)") })] }));
+    const checked = raw !== undefined ? Boolean(raw) : Boolean(props.defaultChecked);
+    const id = useId();
+    return (_jsxs("div", { className: "flex items-center justify-between gap-3", children: [label && (_jsx(Label, { htmlFor: id, className: "font-normal", style: { color: colors.text }, children: label })), _jsx(Switch, { id: id, checked: checked, onCheckedChange: (v) => set(path, v), style: {
+                    backgroundColor: checked ? colors.accent : colors.muted,
+                    borderColor: checked ? colors.accent : colors.inputBorder,
+                } })] }));
 }

package/dist/react/components/text.js

@@ -1,15 +1,10 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { Text, Title } from "@neynar/ui/typography";
+import { Text } from "@neynar/ui/typography";
+import { useSnapColors } from "../hooks/use-snap-colors.js";
 const SIZE_MAP = {
-    lg: { component: "title", textSize: undefined, order: 3 },
-    md: { component: "text", textSize: "base", order: undefined },
-    sm: { component: "text", textSize: "sm", order: undefined },
-};
-const WEIGHT_MAP = {
-    bold: "bold",
-    medium: "medium",
-    normal: "normal",
+    md: { textSize: "base" },
+    sm: { textSize: "sm" },
 };
 export function SnapText({ element: { props }, }) {
     const content = String(props.content ?? "");
@@ -17,9 +12,6 @@ export function SnapText({ element: { props }, }) {
     const weight = props.weight ? String(props.weight) : undefined;
     const align = props.align ?? undefined;
     const config = SIZE_MAP[size] ?? SIZE_MAP.md;
-    const alignClass = align === "center" ? "text-center" : align === "right" ? "text-right" : "";
-    if (config.component === "title") {
-        return (_jsx(Title, { order: config.order, weight: weight ?? "bold", className: `flex-1 ${alignClass}`, children: content }));
-    }
-    return (_jsx(Text, { size: config.textSize, weight: weight, align: align, className: "flex-1", children: content }));
+    const colors = useSnapColors();
+    return (_jsx(Text, { size: config.textSize, weight: weight, align: align, className: "flex-1", style: { color: colors.text }, children: content }));
 }

package/dist/react/components/toggle-group.js

@@ -1,12 +1,13 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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.js";
+import { useSnapColors } from "../hooks/use-snap-colors.js";
 export function SnapToggleGroup({ element: { props }, }) {
     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;
@@ -43,10 +44,23 @@ export function SnapToggleGroup({ element: { props }, }) {
         }
     };
     const isVertical = orientation === "vertical";
-    return (_jsxs("div", { className: "w-full space-y-1.5", style: accentStyle, children: [label && _jsx(Label, { children: label }), _jsx("div", { className: cn("flex gap-1 rounded-lg bg-border/20 p-1", isVertical ? "flex-col" : "flex-row"), children: options.map((opt) => {
+    const [hoveredIdx, setHoveredIdx] = useState(null);
+    return (_jsxs("div", { className: "w-full space-y-1.5", children: [label && _jsx(Label, { style: { color: colors.text }, children: label }), _jsx("div", { className: cn("flex gap-1 rounded-lg p-1", isVertical ? "flex-col" : "flex-row"), style: { backgroundColor: colors.muted }, children: options.map((opt, i) => {
                     const isSelected = selected.includes(opt);
-                    return (_jsx("button", { type: "button", onClick: () => toggle(opt), 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"), children: opt }, opt));
+                    const isHovered = hoveredIdx === i && !isSelected;
+                    return (_jsx("button", { 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"), 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)"),
+                                }),
+                        }, children: opt }, opt));
                 }) })] }));
 }

package/dist/react/hooks/use-snap-colors.d.ts

@@ -0,0 +1,38 @@
+/** Readable foreground color (black or white) for a given hex background. */
+export declare function pickForegroundForBg(hex: string): string;
+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;
+};
+/**
+ * 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 declare function useSnapColors(): SnapColors;

package/dist/react/hooks/use-snap-colors.js

@@ -0,0 +1,81 @@
+"use client";
+import { useMemo } from "react";
+import { useStateStore } from "@json-render/react";
+import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex.js";
+import { useSnapPreviewPageAccent, useSnapAppearance } from "../accent-context.js";
+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) {
+    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)",
+};
+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)",
+};
+function buildSnapColors(accentName, mode) {
+    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) => resolveSnapPaletteHex(name, mode);
+    const colorHex = (name) => {
+        if (!name || name === "accent")
+            return accent;
+        if (Object.hasOwn(paletteMap, name))
+            return paletteMap[name];
+        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() {
+    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/dist/react/index.d.ts

@@ -1,4 +1,6 @@
 import type { Spec } from "@json-render/core";
+import type { ReactNode } from "react";
+import type { ValidationResult } from "../validator.js";
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
@@ -13,6 +15,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;
@@ -39,9 +42,18 @@ export type SnapActionHandlers = {
         buyToken?: string;
     }) => void;
 };
-export declare function SnapView({ snap, handlers, loading, appearance, }: {
+export declare function SnapCard({ snap, handlers, loading, appearance, maxWidth, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, }: {
     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;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/react/index.js

@@ -1,191 +1,12 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { snapJsonRenderCatalog } from "../ui/index.js";
-import { SnapCatalogView } from "./catalog-renderer.js";
-import { SnapPreviewAccentProvider } from "./accent-context.js";
-import { resolveSnapPaletteHex } from "./lib/resolve-palette-hex.js";
-import { snapPreviewPrimaryCssProperties } from "./lib/preview-primary-css.js";
-import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
-// ─── Internal helpers ──────────────────────────────────
-function applyStatePaths(model, changes) {
-    const entries = Array.isArray(changes)
-        ? changes.map((c) => [c.path, c.value])
-        : 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;
-            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;
-            if (rest.length === 1) {
-                theme[rest[0]] = value;
-            }
-        }
+import { jsx as _jsx } from "react/jsx-runtime";
+import { SPEC_VERSION_2 } from "../constants.js";
+import { SnapCardV1 } from "./v1/snap-view.js";
+import { SnapCardV2 } from "./v2/snap-view.js";
+// ─── SnapCard ────────────────────────────────────────
+export function SnapCard({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, }) {
+    if (snap.version === SPEC_VERSION_2) {
+        return (_jsx(SnapCardV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, maxWidth: maxWidth, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, plain: plain }));
     }
-}
-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 (_jsxs("div", { style: {
-            position: "absolute",
-            inset: 0,
-            overflow: "hidden",
-            pointerEvents: "none",
-            zIndex: 20,
-        }, children: [pieces.map(({ id, left, delay, duration, color, size, rotation }) => (_jsx("div", { 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`,
-                } }, id))), _jsx("style", { children: `@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)}}` })] }));
-}
-const PALETTE = [
-    "gray",
-    "blue",
-    "red",
-    "amber",
-    "green",
-    "teal",
-    "purple",
-    "pink",
-];
-// ─── SnapView ──────────────────────────────────────────
-export function SnapView({ snap, handlers, loading = false, appearance = "dark", }) {
-    const spec = snap.ui;
-    const initialState = useMemo(() => spec.state ?? { inputs: {} }, [spec]);
-    const stateRef = useRef(initialState);
-    useEffect(() => {
-        stateRef.current = {
-            inputs: {
-                ...(initialState.inputs ?? {}),
-            },
-            theme: {
-                ...(initialState.theme ?? {}),
-            },
-        };
-    }, [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 = {};
-        for (const c of PALETTE)
-            vars[`--snap-color-${c}`] = resolveSnapPaletteHex(c, appearance);
-        return {
-            ...snapPreviewPrimaryCssProperties(snap.theme?.accent ?? "purple", appearance),
-            ...vars,
-        };
-    }, [snap.theme?.accent, appearance]);
-    const handleAction = useCallback((name, params) => {
-        const inputs = (stateRef.current.inputs ?? {});
-        const p = (params ?? {});
-        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
-                        : 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 (_jsxs("div", { style: { position: "relative", width: "100%" }, children: [showConfetti && _jsx(ConfettiOverlay, {}), loading && (_jsx("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)",
-                }, children: "Loading..." })), _jsx("div", { style: previewSurfaceStyle, children: _jsx(SnapPreviewAccentProvider, { pageAccent: snap.theme?.accent, children: _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
-                            applyStatePaths(stateRef.current, changes);
-                        }, onAction: handleAction }, pageKey) }) })] }));
+    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, maxWidth: maxWidth, actionError: actionError, plain: plain }));
 }

package/dist/react/snap-view-core.d.ts

@@ -0,0 +1,11 @@
+import type { SnapActionHandlers, SnapPage } from "./index.js";
+export declare function applyStatePaths(model: Record<string, unknown>, changes: {
+    path: string;
+    value: unknown;
+}[] | Record<string, unknown>): void;
+export declare function SnapViewCore({ snap, handlers, loading, appearance, }: {
+    snap: SnapPage;
+    handlers: SnapActionHandlers;
+    loading?: boolean;
+    appearance?: "light" | "dark";
+}): import("react/jsx-runtime").JSX.Element;