@farcaster/snap 2.0.2 → 2.1.0

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

@@ -1,7 +1,11 @@
-import { useEffect, useState } from "react";
+import { type ReactNode, 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 {
+  SnapLoadingOverlay,
+  SnapViewCoreInner,
+  resolveAccentHex,
+} from "../snap-view-core";
 import type { SnapPage, SnapActionHandlers } from "../types";
 
 const SNAP_MAX_HEIGHT = 500;
@@ -12,13 +16,20 @@ export function SnapViewV1Inner({
   snap,
   handlers,
   loading = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
   loading?: boolean;
+  loadingOverlay?: ReactNode;
 }) {
   return (
-    <SnapViewCoreInner snap={snap} handlers={handlers} loading={loading} />
+    <SnapViewCoreInner
+      snap={snap}
+      handlers={handlers}
+      loading={loading}
+      loadingOverlay={loadingOverlay}
+    />
   );
 }
 
@@ -28,16 +39,24 @@ export function SnapViewV1({
   loading = false,
   appearance = "dark",
   colors,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
   loading?: boolean;
   appearance?: "light" | "dark";
   colors?: Partial<SnapNativeColors>;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
-      <SnapViewV1Inner snap={snap} handlers={handlers} loading={loading} />
+      <SnapViewV1Inner
+        snap={snap}
+        handlers={handlers}
+        loading={loading}
+        loadingOverlay={loadingOverlay}
+      />
     </SnapThemeProvider>
   );
 }
@@ -52,6 +71,7 @@ function SnapCardV1Inner({
   actionError,
   appearance,
   plain,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -60,8 +80,10 @@ function SnapCardV1Inner({
   actionError?: string | null;
   appearance: "light" | "dark";
   plain: boolean;
+  loadingOverlay?: ReactNode;
 }) {
-  const { colors } = useSnapTheme();
+  const { colors, mode } = useSnapTheme();
+  const accentHex = resolveAccentHex(snap.theme?.accent, mode);
   const [contentHeight, setContentHeight] = useState(0);
   const [isExpanded, setIsExpanded] = useState(false);
 
@@ -73,6 +95,9 @@ function SnapCardV1Inner({
   const isExpandable = contentHeight > SNAP_MAX_HEIGHT + 1;
   const isClipped = isExpandable && !isExpanded;
 
+  const isDark = mode === "dark";
+  const pillBg = isDark ? "rgba(40,40,40,0.92)" : "rgba(255,255,255,0.92)";
+  const pillBgPressed = isDark ? "rgba(60,60,60,0.95)" : "rgba(240,240,240,0.95)";
   return (
     <>
       <View style={cardStyles.frameRing}>
@@ -107,40 +132,38 @@ function SnapCardV1Inner({
                 snap={snap}
                 handlers={handlers}
                 loading={loading}
+                loadingOverlay={null}
               />
             </View>
           </View>
-          {isExpandable ? (
-            <View
-              style={[
-                cardStyles.expandRow,
-                plain
-                  ? cardStyles.expandRowPlain
-                  : { borderTopColor: colors.border },
+          {loading
+            ? loadingOverlay === undefined
+              ? <SnapLoadingOverlay appearance={mode} accentHex={accentHex} />
+              : loadingOverlay
+            : null}
+        </View>
+        {isExpandable ? (
+          <View pointerEvents="box-none" style={cardStyles.expandFloat}>
+            <Pressable
+              style={({ pressed }) => [
+                cardStyles.expandButton,
+                {
+                  backgroundColor: pressed ? pillBgPressed : pillBg,
+                  borderColor: colors.border,
+                },
               ]}
+              onPress={() => {
+                setIsExpanded((value) => !value);
+              }}
             >
-              <Pressable
-                style={({ pressed }) => [
-                  cardStyles.expandButton,
-                  {
-                    backgroundColor: pressed
-                      ? colors.mutedHover
-                      : colors.muted,
-                  },
-                ]}
-                onPress={() => {
-                  setIsExpanded((value) => !value);
-                }}
+              <Text
+                style={[cardStyles.expandButtonText, { color: colors.text }]}
               >
-                <Text
-                  style={[cardStyles.expandButtonText, { color: colors.text }]}
-                >
-                  {isExpanded ? "Show less" : "Show more"}
-                </Text>
-              </Pressable>
-            </View>
-          ) : null}
-        </View>
+                {isExpanded ? "Show less" : "Show more"}
+              </Text>
+            </Pressable>
+          </View>
+        ) : null}
       </View>
       {actionError && (
         <Text
@@ -170,6 +193,7 @@ export function SnapCardV1({
   borderRadius = 16,
   actionError,
   plain = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -179,6 +203,8 @@ export function SnapCardV1({
   borderRadius?: number;
   actionError?: string | null;
   plain?: boolean;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
@@ -190,6 +216,7 @@ export function SnapCardV1({
         actionError={actionError}
         appearance={appearance}
         plain={plain}
+        loadingOverlay={loadingOverlay}
       />
     </SnapThemeProvider>
   );
@@ -199,30 +226,27 @@ const cardStyles = StyleSheet.create({
   frameRing: { alignSelf: "stretch" },
   card: { overflow: "hidden", borderWidth: 1, minHeight: 120 },
   body: { paddingHorizontal: 16, paddingVertical: 16 },
-  expandRow: {
+  expandFloat: {
+    position: "absolute",
+    left: 0,
+    right: 0,
+    bottom: -14,
+    height: 28,
     alignItems: "center",
-    paddingHorizontal: 16,
-    paddingTop: 10,
-    paddingBottom: 12,
-    borderTopWidth: StyleSheet.hairlineWidth,
-  },
-  expandRowPlain: {
-    paddingHorizontal: 0,
-    paddingTop: 8,
-    paddingBottom: 0,
-    borderTopWidth: 0,
+    justifyContent: "center",
   },
   expandButton: {
     minWidth: 92,
     alignItems: "center",
     justifyContent: "center",
     borderRadius: 9999,
+    borderWidth: 1,
     paddingHorizontal: 10,
-    paddingVertical: 6,
+    paddingVertical: 4,
   },
   expandButtonText: {
-    fontSize: 13,
-    lineHeight: 18,
+    fontSize: 12,
+    lineHeight: 16,
     fontWeight: "600",
   },
   actionError: { paddingHorizontal: 12, paddingVertical: 8, fontSize: 13 },

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

@@ -1,8 +1,12 @@
 import type { ReactNode } from "react";
 import { useEffect, useMemo, useState } from "react";
-import { Platform, StyleSheet, Text, View } from "react-native";
+import { Platform, Pressable, StyleSheet, Text, View } from "react-native";
 import { SnapThemeProvider, useSnapTheme, type SnapNativeColors } from "../theme";
-import { SnapViewCoreInner } from "../snap-view-core";
+import {
+  SnapLoadingOverlay,
+  SnapViewCoreInner,
+  resolveAccentHex,
+} from "../snap-view-core";
 import {
   validateSnapResponse,
   type ValidationResult,
@@ -47,12 +51,14 @@ export function SnapViewV2Inner({
   loading = false,
   onValidationError,
   validationErrorFallback,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
   loading?: boolean;
   onValidationError?: (result: ValidationResult) => void;
   validationErrorFallback?: ReactNode;
+  loadingOverlay?: ReactNode;
 }) {
   const validation = useMemo(() => validateSnapResponse(snap), [snap]);
   const valid = validation.valid;
@@ -77,7 +83,12 @@ export function SnapViewV2Inner({
   }
 
   return (
-    <SnapViewCoreInner snap={snap} handlers={handlers} loading={loading} />
+    <SnapViewCoreInner
+      snap={snap}
+      handlers={handlers}
+      loading={loading}
+      loadingOverlay={loadingOverlay}
+    />
   );
 }
 
@@ -89,6 +100,7 @@ export function SnapViewV2({
   colors,
   onValidationError,
   validationErrorFallback,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -97,6 +109,8 @@ export function SnapViewV2({
   colors?: Partial<SnapNativeColors>;
   onValidationError?: (result: ValidationResult) => void;
   validationErrorFallback?: ReactNode;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
@@ -106,6 +120,7 @@ export function SnapViewV2({
         loading={loading}
         onValidationError={onValidationError}
         validationErrorFallback={validationErrorFallback}
+        loadingOverlay={loadingOverlay}
       />
     </SnapThemeProvider>
   );
@@ -124,6 +139,7 @@ function SnapCardV2Inner({
   actionError,
   appearance,
   plain,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -135,9 +151,20 @@ function SnapCardV2Inner({
   actionError?: string | null;
   appearance: "light" | "dark";
   plain: boolean;
+  loadingOverlay?: ReactNode;
 }) {
-  const { colors } = useSnapTheme();
+  const { colors, mode } = useSnapTheme();
+  const accentHex = resolveAccentHex(snap.theme?.accent, mode);
   const [contentHeight, setContentHeight] = useState(0);
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  useEffect(() => {
+    setIsExpanded(false);
+    setContentHeight(0);
+  }, [snap]);
+
+  const isExpandable = !showOverflowWarning && contentHeight > SNAP_MAX_HEIGHT + 1;
+  const isClipped = isExpandable && !isExpanded;
 
   const content = (
     <SnapViewV2Inner
@@ -146,44 +173,124 @@ function SnapCardV2Inner({
       loading={loading}
       onValidationError={onValidationError}
       validationErrorFallback={validationErrorFallback}
+      loadingOverlay={null}
     />
   );
 
   if (plain) {
-    return content;
+    return (
+      <>
+        <View style={isClipped ? { maxHeight: SNAP_MAX_HEIGHT, overflow: "hidden" } : undefined}>
+          <View
+            collapsable={false}
+            onLayout={(e) => {
+              const nextHeight = Math.round(e.nativeEvent.layout.height);
+              setContentHeight((current) =>
+                isClipped
+                  ? Math.max(current, nextHeight)
+                  : current === nextHeight
+                    ? current
+                    : nextHeight,
+              );
+            }}
+          >
+            {content}
+          </View>
+        </View>
+        {loading
+          ? loadingOverlay === undefined
+            ? <SnapLoadingOverlay appearance={mode} accentHex={accentHex} />
+            : loadingOverlay
+          : null}
+        {isExpandable ? (
+          <View style={[cardStyles.expandRow, cardStyles.expandRowPlain]}>
+            <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}
+      </>
+    );
   }
 
   const overflowAmount = showOverflowWarning ? contentHeight - SNAP_MAX_HEIGHT : 0;
+  const isDark = mode === "dark";
+  const pillBg = isDark ? "rgba(40,40,40,0.92)" : "rgba(255,255,255,0.92)";
+  const pillBgPressed = isDark ? "rgba(60,60,60,0.95)" : "rgba(240,240,240,0.95)";
 
   return (
     <>
-      <View
-        style={{
-          borderRadius,
-          borderWidth: 1,
-          borderColor: colors.border,
-          backgroundColor: colors.surface,
-          maxHeight: showOverflowWarning ? undefined : SNAP_MAX_HEIGHT,
-          overflow: "hidden",
-          minHeight: 120,
-        }}
-      >
+      <View style={{ position: "relative" }}>
         <View
-          collapsable={false}
-          onLayout={(e) => setContentHeight(Math.round(e.nativeEvent.layout.height))}
-          style={{ paddingHorizontal: 16, paddingVertical: 16 }}
+          style={{
+            borderRadius,
+            borderWidth: 1,
+            borderColor: colors.border,
+            backgroundColor: colors.surface,
+            maxHeight: showOverflowWarning ? undefined : isClipped ? SNAP_MAX_HEIGHT : undefined,
+            overflow: "hidden",
+            minHeight: 120,
+          }}
         >
-          {content}
-        </View>
-        {showOverflowWarning && contentHeight > SNAP_MAX_HEIGHT && (
-          <View style={{ position: "absolute", top: SNAP_MAX_HEIGHT, left: 0, right: 0, height: overflowAmount, zIndex: 10, pointerEvents: "none" }}>
-            <View style={{ height: 1, borderTopWidth: 1, borderStyle: "dashed", borderColor: "rgba(255,100,100,0.6)" }} />
-            <View style={{ position: "absolute", top: -10, right: 4, backgroundColor: "rgba(0,0,0,0.7)", paddingHorizontal: 4, paddingVertical: 1, borderRadius: 3 }}>
-              <Text style={{ fontSize: 10, color: "rgba(255,100,100,0.7)", fontFamily: Platform.select({ ios: "Menlo", default: "monospace" }) }}>{SNAP_MAX_HEIGHT}px</Text>
+          <View
+            collapsable={false}
+            onLayout={(e) => {
+              const nextHeight = Math.round(e.nativeEvent.layout.height);
+              setContentHeight((current) =>
+                isClipped
+                  ? Math.max(current, nextHeight)
+                  : current === nextHeight
+                    ? current
+                    : nextHeight,
+              );
+            }}
+            style={{ paddingHorizontal: 16, paddingVertical: 16 }}
+          >
+            {content}
+          </View>
+          {showOverflowWarning && contentHeight > SNAP_MAX_HEIGHT && (
+            <View style={{ position: "absolute", top: SNAP_MAX_HEIGHT, left: 0, right: 0, height: overflowAmount, zIndex: 10, pointerEvents: "none" }}>
+              <View style={{ height: 1, borderTopWidth: 1, borderStyle: "dashed", borderColor: "rgba(255,100,100,0.6)" }} />
+              <View style={{ position: "absolute", top: -10, right: 4, backgroundColor: "rgba(0,0,0,0.7)", paddingHorizontal: 4, paddingVertical: 1, borderRadius: 3 }}>
+                <Text style={{ fontSize: 10, color: "rgba(255,100,100,0.7)", fontFamily: Platform.select({ ios: "Menlo", default: "monospace" }) }}>{SNAP_MAX_HEIGHT}px</Text>
+              </View>
+              <View style={{ flex: 1, backgroundColor: "rgba(255,50,50,0.15)" }} />
             </View>
-            <View style={{ flex: 1, backgroundColor: "rgba(255,50,50,0.15)" }} />
+          )}
+          {loading
+            ? loadingOverlay === undefined
+              ? <SnapLoadingOverlay appearance={mode} accentHex={accentHex} />
+              : loadingOverlay
+            : null}
+        </View>
+        {isExpandable ? (
+          <View pointerEvents="box-none" style={cardStyles.expandFloat}>
+            <Pressable
+              style={({ pressed }) => [
+                cardStyles.expandButton,
+                {
+                  backgroundColor: pressed ? pillBgPressed : pillBg,
+                  borderColor: colors.border,
+                },
+              ]}
+              onPress={() => setIsExpanded((value) => !value)}
+            >
+              <Text style={[cardStyles.expandButtonText, { color: colors.text }]}>
+                {isExpanded ? "Show less" : "Show more"}
+              </Text>
+            </Pressable>
           </View>
-        )}
+        ) : null}
       </View>
       {actionError && (
         <Text
@@ -216,6 +323,7 @@ export function SnapCardV2({
   validationErrorFallback,
   actionError,
   plain = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -228,6 +336,8 @@ export function SnapCardV2({
   validationErrorFallback?: ReactNode;
   actionError?: string | null;
   plain?: boolean;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
@@ -242,6 +352,7 @@ export function SnapCardV2({
         actionError={actionError}
         appearance={appearance}
         plain={plain}
+        loadingOverlay={loadingOverlay}
       />
     </SnapThemeProvider>
   );
@@ -252,6 +363,33 @@ const cardStyles = StyleSheet.create({
   card: { borderWidth: 1, minHeight: 120, overflow: "hidden" },
   body: { paddingHorizontal: 16, paddingVertical: 16 },
   actionError: { paddingHorizontal: 12, paddingVertical: 8, fontSize: 13 },
+  expandFloat: {
+    position: "absolute",
+    left: 0,
+    right: 0,
+    bottom: -14,
+    height: 28,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  expandRowPlain: {
+    paddingTop: 8,
+    alignItems: "center",
+  },
+  expandButton: {
+    minWidth: 92,
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 9999,
+    borderWidth: 1,
+    paddingHorizontal: 10,
+    paddingVertical: 4,
+  },
+  expandButtonText: {
+    fontSize: 12,
+    lineHeight: 16,
+    fontWeight: "600",
+  },
   warningOverlay: {
     position: "absolute",
     top: SNAP_MAX_HEIGHT,

package/src/ui/catalog.ts

@@ -58,7 +58,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
     item: {
       props: itemProps,
       description:
-        "Content row with title and optional description. Children render in the actions slot (right side) — use badge, button, or text elements.",
+        "Content row with title and optional description. Children render in the actions slot (right side) — badge, button, and icon elements are all valid. The item itself is not interactive, so avoid navigation-style icons (`chevron-right`, `arrow-right`, `external-link`) that imply the row navigates.",
     },
     item_group: {
       props: itemGroupProps,
@@ -107,7 +107,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
     cell_grid: {
       props: cellGridProps,
       description:
-        "Cell grid — sparse colored cells on a rows×cols grid. Optional gap and selection mode (taps write to inputs[name]).",
+        "Cell grid — sparse colored cells on a rows×cols grid. Two interaction modes: leave select 'off' and bind on.press to fire an action per cell press (inputs[name] is the pressed 'row,col' before the action runs); or set select 'single'/'multiple' for press-to-select with a visual ring (no auto-fire — pair with a separate submit button). on.press is ignored when select is on.",
     },
   },
   actions: {

package/src/validator.ts

@@ -1,6 +1,12 @@
 import { z } from "zod";
 import { snapResponseSchema } from "./schemas";
-import { MAX_CHILDREN, MAX_DEPTH, MAX_ELEMENTS, MAX_ROOT_CHILDREN, SPEC_VERSION_1 } from "./constants";
+import {
+  MAX_CHILDREN,
+  MAX_DEPTH,
+  MAX_ELEMENTS,
+  MAX_ROOT_CHILDREN,
+  SPEC_VERSION_1,
+} from "./constants";
 import { snapJsonRenderCatalog } from "./ui/catalog.js";
 
 export type ValidationResult = {
@@ -18,9 +24,6 @@ const URL_TARGET_ACTIONS = new Set([
   "open_mini_app",
 ]);
 
-/** Image file extensions allowed in image URLs. */
-const ALLOWED_IMAGE_EXTENSIONS = new Set(["jpg", "jpeg", "png", "gif", "webp"]);
-
 /**
  * Returns true if the URL is a loopback address (localhost dev exception).
  */
@@ -48,34 +51,6 @@ function validateUrl(raw: string): string | null {
   return `URL must use HTTPS (got ${url.protocol.replace(":", "")}): "${raw}"`;
 }
 
-/**
- * Validate an image URL: must pass URL validation + have an allowed extension.
- */
-function validateImageUrl(raw: string): string | null {
-  const urlError = validateUrl(raw);
-  if (urlError) return urlError;
-
-  let url: URL;
-  try {
-    url = new URL(raw);
-  } catch {
-    return null; // already caught above
-  }
-
-  const pathname = url.pathname;
-  const lastDot = pathname.lastIndexOf(".");
-  if (lastDot === -1) {
-    return `Image URL must end with a supported extension (${[...ALLOWED_IMAGE_EXTENSIONS].join(", ")}): "${raw}"`;
-  }
-
-  const ext = pathname.slice(lastDot + 1).toLowerCase();
-  if (!ALLOWED_IMAGE_EXTENSIONS.has(ext)) {
-    return `Image URL has unsupported extension ".${ext}" (allowed: ${[...ALLOWED_IMAGE_EXTENSIONS].join(", ")}): "${raw}"`;
-  }
-
-  return null;
-}
-
 // ─── Depth measurement ────────────────────────────────
 
 /**
@@ -118,9 +93,10 @@ type ElementShape = {
  * - Children per element ≤ MAX_CHILDREN
  * - Nesting depth ≤ MAX_DEPTH
  */
-function validateStructure(
-  ui: { root: string; elements: Record<string, unknown> },
-): z.core.$ZodIssue[] {
+function validateStructure(ui: {
+  root: string;
+  elements: Record<string, unknown>;
+}): z.core.$ZodIssue[] {
   const issues: z.core.$ZodIssue[] = [];
   const elements = ui.elements as Record<string, ElementShape>;
 
@@ -173,19 +149,17 @@ function validateStructure(
 
 /**
  * Validate all URLs in the snap:
- * - image.url: must be HTTPS with allowed extension
- * - action target URLs (submit, open_url, open_snap, open_mini_app): must be HTTPS
+ * - image.url: must use HTTPS (or HTTP on loopback for dev)
+ * - action target URLs (submit, open_url, open_snap, open_mini_app): must use HTTPS (or HTTP on loopback for dev)
  */
-function validateUrls(
-  elements: Record<string, unknown>,
-): z.core.$ZodIssue[] {
+function validateUrls(elements: Record<string, unknown>): z.core.$ZodIssue[] {
   const issues: z.core.$ZodIssue[] = [];
   const els = elements as Record<string, ElementShape>;
 
   for (const [id, el] of Object.entries(els)) {
     // Validate image URLs
     if (el.type === "image" && typeof el.props?.url === "string") {
-      const error = validateImageUrl(el.props.url);
+      const error = validateUrl(el.props.url);
       if (error) {
         issues.push({
           code: "custom",
@@ -242,11 +216,13 @@ export function validateSnapResponse(json: unknown): ValidationResult {
   if (!(ui.root in ui.elements)) {
     return {
       valid: false,
-      issues: [{
-        code: "custom",
-        message: `ui.root "${ui.root}" does not exist in ui.elements`,
-        path: ["ui", "root"],
-      }],
+      issues: [
+        {
+          code: "custom",
+          message: `ui.root "${ui.root}" does not exist in ui.elements`,
+          path: ["ui", "root"],
+        },
+      ],
     };
   }