@farcaster/snap 2.5.0 → 2.6.0

package/src/react-native/components/snap-cell-grid.tsx

@@ -4,6 +4,10 @@ import { useStateStore } from "@json-render/react-native";
 import { useSnapPalette } from "../use-snap-palette";
 import { useSnapTheme } from "../theme";
 import { POST_GRID_TAP_KEY, readableTextOnHex } from "@farcaster/snap";
+import {
+  getPaginatorAction,
+  runPaginatorAction,
+} from "../../ui/paginator-state";
 
 export function SnapCellGrid({
   element,
@@ -13,12 +17,21 @@ export function SnapCellGrid({
   const on = (element as unknown as { on?: Record<string, unknown> }).on;
   const { hex, appearance } = useSnapPalette();
   const { colors } = useSnapTheme();
-  const { get, set } = useStateStore();
+  const stateStore = useStateStore();
+  const { get, set } = stateStore;
+  const paginatorAction = getPaginatorAction(on);
   const cols = Number(props.cols ?? 2);
   const rows = Number(props.rows ?? 2);
   const cells = Array.isArray(props.cells) ? props.cells : [];
   const rowHeight = typeof props.rowHeight === "number" ? props.rowHeight : 28;
   const squareCells = props.cellAspectRatio === "square";
+  const maxWidthKey = typeof props.maxWidth === "string" ? props.maxWidth : undefined;
+  const maxWidthMap: Record<string, number | undefined> = {
+    sm: 160,
+    md: 220,
+    lg: undefined,
+  };
+  const maxWidth = maxWidthKey ? maxWidthMap[maxWidthKey] : undefined;
   const gap = String(props.gap ?? "sm");
   const gapMap: Record<string, number> = { none: 0, sm: 1, md: 2, lg: 4 };
   const gapPx = gapMap[gap] ?? 1;
@@ -35,11 +48,12 @@ export function SnapCellGrid({
 
   const cellMap = new Map<
     string,
-    { color?: string; content?: string; value?: string }
+    { color?: string; textColor?: string; content?: string; value?: string }
   >();
   for (const c of cells) {
     cellMap.set(`${Number(c.row)},${Number(c.col)}`, {
       color: c.color as string | undefined,
+      textColor: c.textColor as string | undefined,
       content: c.content != null ? String(c.content) : undefined,
       value: typeof c.value === "string" ? c.value : undefined,
     });
@@ -74,7 +88,12 @@ export function SnapCellGrid({
     } else {
       set(tapPath, wire);
     }
-    if (hasPressAction) emit("press");
+    if (
+      hasPressAction &&
+      !runPaginatorAction(stateStore, paginatorAction)
+    ) {
+      emit("press");
+    }
   };
 
   const ringOuter = appearance === "dark" ? "#fff" : "#000";
@@ -92,7 +111,11 @@ export function SnapCellGrid({
       const selected = interactive && isSelected(r, c);
       const bgHex = cell?.color ? hex(cell.color) : null;
       const bg = bgHex ?? emptyCellBg;
-      const textColor = bgHex ? readableTextOnHex(bgHex) : colors.text;
+      const textColor = cell?.textColor
+        ? hex(cell.textColor)
+        : bgHex
+          ? readableTextOnHex(bgHex)
+          : colors.text;
 
       const cellContent = cell?.content ? (
         <Text style={[styles.cellText, { color: textColor }]}>
@@ -163,6 +186,8 @@ export function SnapCellGrid({
       style={[
         styles.wrap,
         {
+          maxWidth,
+          alignSelf: maxWidth ? "center" : undefined,
           gap: gapPx,
           backgroundColor: colors.muted,
           padding: 4,

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

@@ -1,6 +1,6 @@
 import type { ComponentRenderProps } from "@json-render/react-native";
 import { Image } from "expo-image";
-import { StyleSheet, View } from "react-native";
+import { StyleSheet, Text, View } from "react-native";
 import { useSnapStackDirection } from "../stack-direction-context";
 
 function aspectToRatio(aspect: string): number {
@@ -14,6 +14,9 @@ export function SnapImage({
 }: ComponentRenderProps<Record<string, unknown>>) {
   const url = String(props.url ?? "");
   const alt = String(props.alt ?? "");
+  const title = props.title ? String(props.title) : "";
+  const subtitle = props.subtitle ? String(props.subtitle) : "";
+  const hasOverlay = title.length > 0 || subtitle.length > 0;
   const ratio = aspectToRatio(String(props.aspect ?? "1:1"));
   const stackDir = useSnapStackDirection();
   const inHorizontalStack = stackDir === "horizontal";
@@ -32,6 +35,20 @@ export function SnapImage({
         contentFit="cover"
         accessibilityLabel={alt || undefined}
       />
+      {hasOverlay ? (
+        <View style={styles.overlay}>
+          {title ? (
+            <Text numberOfLines={1} style={styles.title}>
+              {title}
+            </Text>
+          ) : null}
+          {subtitle ? (
+            <Text numberOfLines={1} style={styles.subtitle}>
+              {subtitle}
+            </Text>
+          ) : null}
+        </View>
+      ) : null}
     </View>
   );
 }
@@ -49,4 +66,26 @@ const styles = StyleSheet.create({
     flex: 1,
     minWidth: 0,
   },
+  overlay: {
+    position: "absolute",
+    left: 0,
+    right: 0,
+    bottom: 0,
+    paddingHorizontal: 12,
+    paddingTop: 24,
+    paddingBottom: 10,
+    backgroundColor: "rgba(0, 0, 0, 0.48)",
+  },
+  title: {
+    color: "#fff",
+    fontSize: 14,
+    lineHeight: 18,
+    fontWeight: "700",
+  },
+  subtitle: {
+    color: "rgba(255, 255, 255, 0.85)",
+    fontSize: 12,
+    lineHeight: 16,
+    fontWeight: "500",
+  },
 });

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

@@ -0,0 +1,283 @@
+import type { ComponentRenderProps } from "@json-render/react-native";
+import { useStateStore } from "@json-render/react-native";
+import {
+  Children,
+  type ReactNode,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { Animated, Pressable, StyleSheet, View } from "react-native";
+import { ChevronLeft, ChevronRight } from "lucide-react-native";
+import { useSnapPalette } from "../use-snap-palette";
+import { useSnapTheme } from "../theme";
+import {
+  clampPaginatorPage,
+  pageFromValue,
+  SNAP_PAGINATOR_PAGE_COUNT_PATH,
+  SNAP_PAGINATOR_PAGE_PATH,
+} from "../../ui/paginator-state";
+
+function clampInitialPage(value: unknown, pageCount: number): number {
+  if (typeof value !== "number" || !Number.isInteger(value)) return 0;
+  return Math.min(Math.max(value, 0), Math.max(pageCount - 1, 0));
+}
+
+export function SnapPaginator({
+  element: { props },
+  children,
+}: ComponentRenderProps<Record<string, unknown>> & { children?: ReactNode }) {
+  const pages = useMemo(
+    () => Children.toArray(children),
+    [children],
+  );
+  const { colors, mode } = useSnapTheme();
+  const { accentHex } = useSnapPalette();
+  const { get, set } = useStateStore();
+  const initialPage = clampInitialPage(props.initialPage, pages.length);
+  const page = clampPaginatorPage(
+    pageFromValue(get(SNAP_PAGINATOR_PAGE_PATH), initialPage),
+    pages.length,
+  );
+  const activePage = Math.min(page, Math.max(pages.length - 1, 0));
+  const showControls = props.showControls !== false && pages.length > 1;
+  const showIndicators = props.showIndicators !== false && pages.length > 1;
+  const controlsPosition = props.controlsPosition === "top" ? "top" : "bottom";
+  const transition =
+    props.transition === "fade" ||
+    props.transition === "scale" ||
+    props.transition === "none"
+      ? props.transition
+      : "slide";
+  const showControlBar = showControls || showIndicators;
+  const [transitionDirection, setTransitionDirection] =
+    useState<"next" | "previous">("next");
+  const pageAnim = useRef(new Animated.Value(1)).current;
+
+  const canGoPrev = activePage > 0;
+  const canGoNext = activePage < pages.length - 1;
+  const goToPage = (targetPage: number) => {
+    const nextPage = clampPaginatorPage(targetPage, pages.length);
+    if (nextPage !== activePage) {
+      setTransitionDirection(nextPage > activePage ? "next" : "previous");
+    }
+    set(SNAP_PAGINATOR_PAGE_PATH, nextPage);
+  };
+  const goPrev = () => goToPage(activePage - 1);
+  const goNext = () => goToPage(activePage + 1);
+
+  useEffect(() => {
+    if (pages.length === 0) return;
+    const nextPage = clampPaginatorPage(
+      pageFromValue(get(SNAP_PAGINATOR_PAGE_PATH), initialPage),
+      pages.length,
+    );
+    if (get(SNAP_PAGINATOR_PAGE_PATH) !== nextPage) {
+      set(SNAP_PAGINATOR_PAGE_PATH, nextPage);
+    }
+    if (get(SNAP_PAGINATOR_PAGE_COUNT_PATH) !== pages.length) {
+      set(SNAP_PAGINATOR_PAGE_COUNT_PATH, pages.length);
+    }
+  }, [get, initialPage, pages.length, set]);
+
+  useEffect(() => {
+    if (transition === "none") {
+      pageAnim.setValue(1);
+      return;
+    }
+    pageAnim.setValue(0);
+    Animated.timing(pageAnim, {
+      toValue: 1,
+      duration: transition === "scale" ? 240 : transition === "slide" ? 260 : 180,
+      useNativeDriver: true,
+    }).start();
+  }, [activePage, pageAnim, transition]);
+
+  if (pages.length === 0) return null;
+
+  const controlBar = showControlBar ? (
+    <View style={styles.footer}>
+      {showControls ? (
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel="Previous page"
+          disabled={!canGoPrev}
+          onPress={goPrev}
+          style={[
+            styles.control,
+            {
+              borderColor: colors.border,
+              backgroundColor: colors.muted,
+              opacity: canGoPrev ? 1 : 0.35,
+            },
+          ]}
+        >
+          <ChevronLeft size={15} color={colors.text} />
+        </Pressable>
+      ) : (
+        <View style={styles.controlPlaceholder} />
+      )}
+
+      {showIndicators ? (
+        <View style={styles.indicators}>
+          {pages.map((_, index) => {
+            const current = index === activePage;
+            return (
+              <View
+                key={index}
+                accessibilityLabel={`Page ${index + 1}${current ? ", current" : ""}`}
+                style={[
+                  styles.dot,
+                  current ? styles.dotCurrent : styles.dotInactive,
+                  {
+                    backgroundColor: current
+                      ? accentHex
+                      : mode === "dark"
+                        ? "rgba(255,255,255,0.5)"
+                        : "rgba(0,0,0,0.28)",
+                    borderColor: current
+                      ? mode === "dark"
+                        ? "rgba(255,255,255,0.18)"
+                        : "rgba(0,0,0,0.12)"
+                      : "transparent",
+                  },
+                ]}
+              />
+            );
+          })}
+        </View>
+      ) : (
+        <View style={styles.indicators} />
+      )}
+
+      {showControls ? (
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel="Next page"
+          disabled={!canGoNext}
+          onPress={goNext}
+          style={[
+            styles.control,
+            {
+              borderColor: colors.border,
+              backgroundColor: colors.muted,
+              opacity: canGoNext ? 1 : 0.35,
+            },
+          ]}
+        >
+          <ChevronRight size={15} color={colors.text} />
+        </Pressable>
+      ) : (
+        <View style={styles.controlPlaceholder} />
+      )}
+    </View>
+  ) : null;
+
+  const animatedPageStyle =
+    transition === "none"
+      ? undefined
+      : {
+          opacity: pageAnim.interpolate({
+            inputRange: [0, 1],
+            outputRange: [transition === "fade" ? 0.2 : 0.35, 1],
+          }),
+          transform:
+            transition === "scale"
+              ? [
+                  {
+                    scale: pageAnim.interpolate({
+                      inputRange: [0, 1],
+                      outputRange: [0.94, 1],
+                    }),
+                  },
+                ]
+              : transition === "slide"
+                ? [
+                    {
+                      translateX: pageAnim.interpolate({
+                        inputRange: [0, 1],
+                        outputRange: [
+                          transitionDirection === "previous" ? -22 : 22,
+                          0,
+                        ],
+                      }),
+                    },
+                    {
+                      scale: pageAnim.interpolate({
+                        inputRange: [0, 1],
+                        outputRange: [0.985, 1],
+                      }),
+                    },
+                  ]
+                : [],
+        };
+
+  return (
+    <View style={styles.wrap}>
+      {controlsPosition === "top" ? controlBar : null}
+      <Animated.View
+        style={[
+          styles.page,
+          animatedPageStyle,
+        ]}
+      >
+        {pages[activePage]}
+      </Animated.View>
+      {controlsPosition === "bottom" ? controlBar : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  wrap: {
+    width: "100%",
+    minWidth: 0,
+    gap: 8,
+  },
+  page: {
+    width: "100%",
+    minWidth: 0,
+  },
+  footer: {
+    minHeight: 28,
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: 8,
+  },
+  control: {
+    width: 28,
+    height: 28,
+    borderWidth: 1,
+    borderRadius: 6,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  controlPlaceholder: {
+    width: 28,
+    height: 28,
+  },
+  indicators: {
+    flex: 1,
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: 6,
+  },
+  dot: {
+    borderWidth: 0,
+    overflow: "hidden",
+  },
+  dotInactive: {
+    width: 8,
+    height: 8,
+    borderRadius: 4,
+  },
+  dotCurrent: {
+    width: 10,
+    height: 10,
+    borderRadius: 5,
+    borderWidth: 2,
+  },
+});

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

@@ -1,11 +1,12 @@
 import type { ComponentRenderProps } from "@json-render/react-native";
 import { StyleSheet, Text, View } from "react-native";
 import { useSnapStackDirection } from "../stack-direction-context";
+import { useSnapVersion } from "../snap-version-context";
 import { useSnapTheme } from "../theme";
 
 const SIZE_STYLES: Record<string, { fontSize: number; lineHeight?: number; fontWeight?: "400" | "500" | "600" | "700" }> = {
-  md: { fontSize: 16, lineHeight: 24 },
-  sm: { fontSize: 13, lineHeight: 18 },
+  md: { fontSize: 16, lineHeight: 22 },
+  sm: { fontSize: 13, lineHeight: 16 },
 };
 
 const WEIGHT_MAP: Record<string, "400" | "500" | "600" | "700"> = {
@@ -21,11 +22,18 @@ export function SnapText({
   const size = String(props.size ?? "md");
   const weight = props.weight ? String(props.weight) : undefined;
   const align = (props.align as "left" | "center" | "right" | undefined) ?? undefined;
+  const snapVersion = useSnapVersion();
 
   const sizeStyle = SIZE_STYLES[size] ?? SIZE_STYLES.md;
   const resolvedWeight = weight ? WEIGHT_MAP[weight] : sizeStyle?.fontWeight;
   const textAlign = align === "center" ? "center" : align === "right" ? "right" : "left";
   const inHorizontalStack = useSnapStackDirection() === "horizontal";
+  const maxLines =
+    typeof props.maxLines === "number"
+      ? props.maxLines
+      : snapVersion === "2.0"
+        ? 1
+        : undefined;
 
   return (
     <View style={inHorizontalStack ? styles.wrapRow : styles.wrapCol}>
@@ -40,6 +48,7 @@ export function SnapText({
             textAlign,
           },
         ]}
+        numberOfLines={maxLines}
       >
         {content}
       </Text>

package/src/react-native/expand-state.ts

@@ -0,0 +1,48 @@
+export const SNAP_MAX_HEIGHT = 500;
+
+export type SnapExpansionOptions = {
+  contentHeight: number;
+  internalExpanded: boolean;
+  forceExpanded?: boolean;
+  onExpandPress?: (() => void) | undefined;
+  expandButtonLabel?: string | undefined;
+  showOverflowWarning?: boolean | undefined;
+};
+
+export type SnapExpansionState = {
+  expandable: boolean;
+  clipped: boolean;
+  showButton: boolean;
+  buttonLabel: string;
+  useInternalToggle: boolean;
+  showOverflowWarning: boolean;
+  maxHeight: number | undefined;
+};
+
+export function getSnapExpansionState({
+  contentHeight,
+  internalExpanded,
+  forceExpanded = false,
+  onExpandPress,
+  expandButtonLabel,
+  showOverflowWarning = false,
+}: SnapExpansionOptions): SnapExpansionState {
+  const hostControlled = typeof onExpandPress === "function";
+  const overflowWarning = showOverflowWarning && !forceExpanded;
+  const expandable =
+    !forceExpanded && !overflowWarning && contentHeight > SNAP_MAX_HEIGHT + 1;
+  const clipped = expandable && !internalExpanded;
+  const showButton = expandable;
+  const useInternalToggle = !hostControlled;
+
+  return {
+    expandable,
+    clipped,
+    showButton,
+    buttonLabel:
+      clipped && expandButtonLabel ? expandButtonLabel : internalExpanded ? "Show less" : "Show more",
+    useInternalToggle,
+    showOverflowWarning: overflowWarning,
+    maxHeight: clipped ? SNAP_MAX_HEIGHT : undefined,
+  };
+}

package/src/react-native/index.tsx

@@ -32,6 +32,9 @@ export function SnapCard({
   actionError,
   plain = false,
   loadingOverlay,
+  forceExpanded,
+  expandButtonLabel,
+  onExpandPress,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -52,6 +55,12 @@ export function SnapCard({
   plain?: boolean;
   /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
   loadingOverlay?: ReactNode;
+  /** When true, render full content height without 500px clipping or expand controls. */
+  forceExpanded?: boolean;
+  /** Custom label for the collapsed expand button. */
+  expandButtonLabel?: string;
+  /** Called from the collapsed expand button instead of toggling internal state. */
+  onExpandPress?: () => void;
 }) {
   if (snap.version === SPEC_VERSION_2) {
     return (
@@ -68,6 +77,9 @@ export function SnapCard({
         actionError={actionError}
         plain={plain}
         loadingOverlay={loadingOverlay}
+        forceExpanded={forceExpanded}
+        expandButtonLabel={expandButtonLabel}
+        onExpandPress={onExpandPress}
       />
     );
   }
@@ -83,6 +95,9 @@ export function SnapCard({
       actionError={actionError}
       plain={plain}
       loadingOverlay={loadingOverlay}
+      forceExpanded={forceExpanded}
+      expandButtonLabel={expandButtonLabel}
+      onExpandPress={onExpandPress}
     />
   );
 }

package/src/react-native/snap-version-context.tsx

@@ -0,0 +1,10 @@
+import { createContext, useContext } from "react";
+import type { SpecVersion } from "@farcaster/snap";
+
+const SnapVersionContext = createContext<SpecVersion>("1.0");
+
+export const SnapVersionProvider = SnapVersionContext.Provider;
+
+export function useSnapVersion(): SpecVersion {
+  return useContext(SnapVersionContext);
+}

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

@@ -4,6 +4,7 @@ import { SnapCatalogView } from "./catalog-renderer";
 import { ConfettiOverlay } from "./confetti-overlay";
 import { FireworksOverlay } from "./fireworks-overlay";
 import { useSnapTheme } from "./theme";
+import { SnapVersionProvider } from "./snap-version-context";
 import {
   type ReactNode,
   useCallback,
@@ -25,8 +26,13 @@ import type { SnapPage, SnapActionHandlers, JsonValue } from "./types";
 
 export function applyStatePaths(
   model: Record<string, unknown>,
-  changes: { path: string; value: unknown }[] | Record<string, unknown>,
+  changes:
+    | { path: string; value: unknown }[]
+    | Record<string, unknown>
+    | null
+    | undefined,
 ): void {
+  if (!changes) return;
   const entries = Array.isArray(changes)
     ? changes.map((c) => [c.path, c.value] as const)
     : Object.entries(changes);
@@ -57,6 +63,30 @@ export function applyStatePaths(
   }
 }
 
+function withDefaultElementProps(spec: Spec): Spec {
+  if (!spec || typeof spec !== "object" || !("elements" in spec)) return spec;
+  const elements = spec.elements as unknown as Record<
+    string,
+    Record<string, unknown>
+  >;
+  if (!elements || typeof elements !== "object") return spec;
+
+  let changed = false;
+  const nextElements: Record<string, Record<string, unknown>> = {};
+  for (const [id, element] of Object.entries(elements)) {
+    if (element.props !== undefined) {
+      nextElements[id] = element;
+      continue;
+    }
+    changed = true;
+    nextElements[id] = { ...element, props: {} };
+  }
+
+  return changed
+    ? ({ ...spec, elements: nextElements } as unknown as Spec)
+    : spec;
+}
+
 export function resolveAccentHex(
   accent: string | undefined,
   appearance: "light" | "dark",
@@ -87,7 +117,10 @@ export function SnapViewCoreInner({
   loadingOverlay?: ReactNode;
 }) {
   const { mode } = useSnapTheme();
-  const spec = snap.ui;
+  const spec = useMemo(
+    () => withDefaultElementProps(snap.ui as unknown as Spec) as SnapPage["ui"],
+    [snap.ui],
+  );
   const accentHex = resolveAccentHex(snap.theme?.accent, mode);
 
   const initialState = useMemo(
@@ -206,16 +239,18 @@ export function SnapViewCoreInner({
           )
           : loadingOverlay
         : null}
-      <SnapCatalogView
-        key={pageKey}
-        spec={spec}
-        state={initialState}
-        loading={false}
-        onStateChange={(changes) => {
-          applyStatePaths(stateRef.current, changes);
-        }}
-        onAction={handleAction}
-      />
+      <SnapVersionProvider value={snap.version === "2.0" ? "2.0" : "1.0"}>
+        <SnapCatalogView
+          key={pageKey}
+          spec={spec}
+          state={initialState}
+          loading={false}
+          onStateChange={(changes) => {
+            applyStatePaths(stateRef.current, changes);
+          }}
+          onAction={handleAction}
+        />
+      </SnapVersionProvider>
       {showConfetti && <ConfettiOverlay key={confettiKey} />}
       {showFireworks && <FireworksOverlay key={fireworksKey} />}
     </View>