@farcaster/snap 2.3.1 → 2.5.0

package/src/react-native/components/snap-item-group.tsx

@@ -2,8 +2,14 @@ import type { ComponentRenderProps } from "@json-render/react-native";
 import { Children, Fragment, type ReactNode } from "react";
 import { StyleSheet, View } from "react-native";
 import { useSnapTheme } from "../theme";
+import { SnapItemGroupBorderProvider } from "./item-layout-context";
 
-const GAP_MAP: Record<string, number> = { none: 0, sm: 4, md: 8, lg: 12 };
+const GAP_MAP: Record<string, number> = {
+  none: 0,
+  sm: 4,
+  md: 8,
+  lg: 12,
+};
 
 export function SnapItemGroup({
   element: { props },
@@ -16,22 +22,30 @@ export function SnapItemGroup({
   const items = Children.toArray(children);
 
   return (
-    <View
-      style={[
-        styles.group,
-        border && { borderWidth: 1, borderColor: colors.border, borderRadius: 12 },
-        { gap },
-      ]}
-    >
-      {items.map((child, i) => (
-        <Fragment key={i}>
-          {separator && i > 0 && (
-            <View style={{ height: 1, backgroundColor: colors.border + "80" }} />
-          )}
-          {child}
-        </Fragment>
-      ))}
-    </View>
+    <SnapItemGroupBorderProvider value={border}>
+      <View
+        style={[
+          styles.group,
+          border && {
+            borderWidth: 1,
+            borderColor: colors.border,
+            borderRadius: 12,
+          },
+          { gap },
+        ]}
+      >
+        {items.map((child, i) => (
+          <Fragment key={i}>
+            {separator && i > 0 && (
+              <View
+                style={{ height: 1, backgroundColor: colors.border + "80" }}
+              />
+            )}
+            {child}
+          </Fragment>
+        ))}
+      </View>
+    </SnapItemGroupBorderProvider>
   );
 }
 

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

@@ -1,33 +1,98 @@
 import type { ComponentRenderProps } from "@json-render/react-native";
+import { Image } from "expo-image";
 import type { ReactNode } from "react";
 import { StyleSheet, Text, View } from "react-native";
 import { useSnapStackDirection } from "../stack-direction-context";
 import { useSnapTheme } from "../theme";
+import { useSnapPalette } from "../use-snap-palette";
+import { useSnapItemGroupHasBorder } from "./item-layout-context";
+import { ICON_MAP } from "./snap-icon";
+
+type ItemMediaConfig =
+  | {
+      variant: "icon";
+      name: string;
+      color?: string;
+    }
+  | {
+      variant: "image";
+      url: string;
+      alt?: string;
+      round?: boolean;
+    };
+
+function parseItemMedia(value: unknown): ItemMediaConfig | undefined {
+  if (!value || typeof value !== "object") return undefined;
+
+  const media = value as Record<string, unknown>;
+  if (media.variant === "icon" && typeof media.name === "string") {
+    return {
+      variant: "icon",
+      name: media.name,
+      color: typeof media.color === "string" ? media.color : undefined,
+    };
+  }
+
+  if (media.variant === "image" && typeof media.url === "string") {
+    return {
+      variant: "image",
+      url: media.url,
+      alt: typeof media.alt === "string" ? media.alt : undefined,
+      round: typeof media.round === "boolean" ? media.round : undefined,
+    };
+  }
+
+  return undefined;
+}
 
 export function SnapItem({
   element: { props },
   children,
 }: ComponentRenderProps<Record<string, unknown>> & { children?: ReactNode }) {
   const { colors } = useSnapTheme();
+  const { accentHex, hex } = useSnapPalette();
   const title = String(props.title ?? "");
-  const description = props.description
-    ? String(props.description)
-    : undefined;
+  const description = props.description ? String(props.description) : undefined;
+  const media = parseItemMedia(props.media);
+  const inBorderedGroup = useSnapItemGroupHasBorder();
   /** Match web `Item className="flex-1"`: row peers must share width or title/description collapse. */
   const rowPeer = useSnapStackDirection() === "horizontal";
+  const MediaIcon =
+    media?.variant === "icon" ? ICON_MAP[media.name] : undefined;
+  const mediaColor =
+    media?.variant === "icon" && media.color && media.color !== "accent"
+      ? hex(media.color)
+      : accentHex;
 
-  const containerVariant = { paddingVertical: 6, paddingHorizontal: 10 };
+  const containerVariant = {
+    paddingVertical: 6,
+    paddingHorizontal: inBorderedGroup ? 8 : 0,
+    columnGap: 8,
+  };
 
   return (
     <View
-      style={[
-        styles.container,
-        containerVariant,
-        rowPeer && styles.rowPeer,
-      ]}
+      style={[styles.container, containerVariant, rowPeer && styles.rowPeer]}
     >
+      {media?.variant === "icon" && MediaIcon ? (
+        <View style={styles.iconMedia}>
+          <MediaIcon size={20} color={mediaColor} />
+        </View>
+      ) : null}
+      {media?.variant === "image" ? (
+        <View style={[styles.imageMedia, media.round && styles.roundImage]}>
+          <Image
+            source={{ uri: media.url }}
+            style={StyleSheet.absoluteFill}
+            contentFit="cover"
+            accessibilityLabel={media.alt || undefined}
+          />
+        </View>
+      ) : null}
       <View style={styles.content}>
-        {title ? <Text style={[styles.title, { color: colors.text }]}>{title}</Text> : null}
+        {title ? (
+          <Text style={[styles.title, { color: colors.text }]}>{title}</Text>
+        ) : null}
         {description ? (
           <Text style={[styles.description, { color: colors.textSecondary }]}>
             {description}
@@ -55,19 +120,32 @@ const styles = StyleSheet.create({
   content: {
     flex: 1,
   },
+  iconMedia: {
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  imageMedia: {
+    width: 40,
+    height: 40,
+    borderRadius: 6,
+    overflow: "hidden",
+    backgroundColor: "#f3f4f6",
+  },
+  roundImage: {
+    borderRadius: 9999,
+  },
   title: {
     fontSize: 15,
     lineHeight: 20,
     fontWeight: "500",
   },
   description: {
-    fontSize: 13,
-    lineHeight: 18,
-    marginTop: 1,
+    fontSize: 12,
+    lineHeight: 16,
   },
   actions: {
     marginLeft: "auto",
-    paddingLeft: 12,
+    paddingLeft: 8,
     flexDirection: "row",
     alignItems: "center",
     flexShrink: 0,

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

@@ -2,9 +2,10 @@ import type { ComponentRenderProps } from "@json-render/react-native";
 import { Children, type ReactNode } from "react";
 import { StyleSheet, View } from "react-native";
 import {
+  childrenShouldUseHorizontalButtonLayout,
+  childrenAreAllButtons,
   countRenderableChildren,
   defaultHorizontalGapSize,
-  horizontalChildrenAreAllButtons,
 } from "../../stack-horizontal-utils.js";
 import {
   SnapStackDirectionProvider,
@@ -13,7 +14,7 @@ import {
 
 const VGAP: Record<string, number> = {
   none: 0,
-  sm: 8,
+  sm: 4,
   md: 16,
   lg: 24,
 };
@@ -33,7 +34,7 @@ const JUSTIFY: Record<string, "flex-start" | "center" | "flex-end" | "space-betw
   around: "space-around",
 };
 
-/** Equal-width cells for explicit `columns` and all-button horizontal rows. */
+/** Equal-width cells for explicit `equalWidth` / `columns` props. */
 function wrapEqualColumnCells(children: ReactNode): ReactNode {
   const cells = Children.toArray(children).filter(
     (c) => c != null && c !== false,
@@ -50,17 +51,21 @@ export function SnapStack({
   children,
 }: ComponentRenderProps<Record<string, unknown>> & { children?: ReactNode }) {
   const parentDirection = useSnapStackDirection();
-  const direction = String(props.direction ?? "vertical");
+  const buttonContentUsesHorizontal =
+    childrenShouldUseHorizontalButtonLayout(children);
+  const direction =
+    buttonContentUsesHorizontal === undefined
+      ? String(props.direction ?? "vertical")
+      : buttonContentUsesHorizontal
+        ? "horizontal"
+        : "vertical";
   const rawGap = props.gap;
   const isHorizontal = direction === "horizontal";
   const gapMap = isHorizontal ? HGAP : VGAP;
-  const buttonRowGrid =
-    isHorizontal && horizontalChildrenAreAllButtons(children);
-  const buttonRowCount = buttonRowGrid
-    ? countRenderableChildren(children)
-    : 0;
+  const allChildrenAreButtons = childrenAreAllButtons(children);
 
   const columnsRaw = props.columns;
+  const equalWidth = props.equalWidth === true;
   const columns =
     typeof columnsRaw === "number" &&
     columnsRaw >= 2 &&
@@ -69,49 +74,44 @@ export function SnapStack({
       ? columnsRaw
       : undefined;
 
-  // Horizontal default depends on column count: 2→lg, 3→md, 4+→sm. Vertical stays md.
-  // Count comes from explicit `columns`, then button-row inference, else direct children
-  // count (any horizontal stack is N columns wide regardless of child types).
-  const horizontalColumnCount = isHorizontal
-    ? (columns ??
-       (buttonRowGrid ? buttonRowCount : undefined) ??
-       countRenderableChildren(children))
+  const equalWidthColumnCount =
+    columns ?? (equalWidth ? countRenderableChildren(children) : undefined);
+  const explicitEqualWidth =
+    isHorizontal &&
+    equalWidthColumnCount !== undefined &&
+    equalWidthColumnCount >= 1 &&
+    equalWidthColumnCount <= 6;
+
+  // Button-only stacks always default to sm; mixed horizontal stacks scale by child count.
+  // Vertical non-button stacks default to md.
+  const horizontalChildCount = isHorizontal
+    ? (explicitEqualWidth
+        ? equalWidthColumnCount
+        : countRenderableChildren(children))
     : undefined;
   const gap =
     typeof rawGap === "number"
       ? rawGap
       : typeof rawGap === "string" && rawGap in gapMap
         ? gapMap[rawGap]!
-        : isHorizontal
-          ? gapMap[defaultHorizontalGapSize(horizontalColumnCount)]!
+        : allChildrenAreButtons
+          ? gapMap.sm!
+          : isHorizontal
+          ? gapMap[defaultHorizontalGapSize(horizontalChildCount)]!
           : VGAP.md!;
-  const explicitColumnGrid =
-    isHorizontal && columns !== undefined && !buttonRowGrid;
-
   const justify =
     props.justify &&
-    (!isHorizontal || (!buttonRowGrid && !explicitColumnGrid))
+    (!isHorizontal || !explicitEqualWidth)
       ? JUSTIFY[String(props.justify)]
       : undefined;
 
   const isRowChild = parentDirection === "horizontal";
 
   const packedHorizontal =
-    isHorizontal &&
-    ((buttonRowGrid &&
-      buttonRowCount >= 1 &&
-      buttonRowCount <= 6) ||
-      explicitColumnGrid);
+    isHorizontal && explicitEqualWidth;
 
   let horizontalBody: ReactNode = children;
-  if (
-    isHorizontal &&
-    buttonRowGrid &&
-    buttonRowCount >= 1 &&
-    buttonRowCount <= 6
-  ) {
-    horizontalBody = wrapEqualColumnCells(children);
-  } else if (isHorizontal && explicitColumnGrid && columns !== undefined) {
+  if (isHorizontal && explicitEqualWidth) {
     horizontalBody = wrapEqualColumnCells(children);
   }
 
@@ -163,7 +163,7 @@ const styles = StyleSheet.create({
     width: "100%",
     minWidth: 0,
   },
-  /** Single row for packed equal-width cells (button grids & explicit columns). */
+  /** Single row for packed equal-width cells from explicit equal-width layout. */
   horizontalPacked: {
     flexDirection: "row",
     flexWrap: "nowrap",
@@ -176,5 +176,6 @@ const styles = StyleSheet.create({
     flexShrink: 1,
     flexBasis: 0,
     minWidth: 0,
+    alignSelf: "stretch",
   },
 });

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

@@ -1,6 +1,7 @@
 import type { ComponentRenderProps } from "@json-render/react-native";
 import { useStateStore } from "@json-render/react-native";
 import { Pressable, StyleSheet, Text, View } from "react-native";
+import { shouldUseHorizontalButtonContent } from "../../button-orientation-utils.js";
 import { useSnapTheme } from "../theme";
 
 export function SnapToggleGroup({
@@ -12,7 +13,6 @@ export function SnapToggleGroup({
   const path = `/inputs/${name}`;
   const label = props.label ? String(props.label) : undefined;
   const isMultiple = Boolean(props.multiple);
-  const orientation = String(props.orientation ?? "horizontal");
   const options = Array.isArray(props.options)
     ? (props.options as string[])
     : [];
@@ -38,7 +38,7 @@ export function SnapToggleGroup({
     return [];
   })();
 
-  const isVertical = orientation === "vertical";
+  const isVertical = !shouldUseHorizontalButtonContent(options);
 
   const handlePress = (opt: string) => {
     if (isMultiple) {
@@ -65,7 +65,7 @@ export function SnapToggleGroup({
           const isSelected = selected.includes(opt);
           return (
             <Pressable
-              key={index}
+              key={`${opt}-${index}`}
               style={({ pressed }) => [
                 styles.option,
                 {
@@ -117,7 +117,8 @@ const styles = StyleSheet.create({
     justifyContent: "center",
   },
   optionHorizontal: {
-    flex: 1,
+    flexGrow: 1,
+    flexShrink: 1,
   },
   optionText: {
     fontSize: 13,

package/src/react-native/fireworks-overlay.tsx

@@ -0,0 +1,176 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Animated, StyleSheet, View, useWindowDimensions } from "react-native";
+
+const FIREWORK_COLORS = [
+  "#FFD700",
+  "#FF6B6B",
+  "#4ECDC4",
+  "#C4A7E7",
+  "#F6C177",
+  "#EBBCBA",
+  "#9CCFD8",
+  "#fff",
+];
+
+const BURST_COUNT = 5;
+const PARTICLE_COUNT = 24;
+
+type BurstData = {
+  id: number;
+  x: number;
+  y: number;
+  particles: Array<{
+    id: number;
+    vx: number;
+    vy: number;
+    color: string;
+    size: number;
+  }>;
+};
+
+function FireworkBurst({ burst }: { burst: BurstData }) {
+  const flashAnim = useRef(new Animated.Value(0)).current;
+  const burstAnim = useRef(new Animated.Value(0)).current;
+
+  useEffect(() => {
+    const composite = Animated.parallel([
+      Animated.timing(flashAnim, {
+        toValue: 1,
+        duration: 400,
+        useNativeDriver: true,
+      }),
+      Animated.timing(burstAnim, {
+        toValue: 1,
+        duration: 1000,
+        useNativeDriver: true,
+      }),
+    ]);
+    composite.start();
+    return () => composite.stop();
+  }, [flashAnim, burstAnim]);
+
+  const flashOpacity = flashAnim.interpolate({
+    inputRange: [0, 0.25, 1],
+    outputRange: [0, 1, 0],
+  });
+  const flashScale = flashAnim.interpolate({
+    inputRange: [0, 0.25, 1],
+    outputRange: [0, 2.5, 5],
+  });
+
+  return (
+    <>
+      <Animated.View
+        style={[
+          styles.flash,
+          {
+            left: burst.x - 6,
+            top: burst.y - 6,
+            opacity: flashOpacity,
+            transform: [{ scale: flashScale }],
+          },
+        ]}
+      />
+      {burst.particles.map((p) => {
+        const opacity = burstAnim.interpolate({
+          inputRange: [0, 0.65, 1],
+          outputRange: [1, 1, 0],
+        });
+        const translateX = burstAnim.interpolate({
+          inputRange: [0, 1],
+          outputRange: [0, p.vx],
+        });
+        const translateY = burstAnim.interpolate({
+          inputRange: [0, 1],
+          outputRange: [0, p.vy],
+        });
+        const scale = burstAnim.interpolate({
+          inputRange: [0, 1],
+          outputRange: [1, 0],
+        });
+        return (
+          <Animated.View
+            key={p.id}
+            style={[
+              styles.particle,
+              {
+                left: burst.x - p.size / 2,
+                top: burst.y - p.size / 2,
+                width: p.size,
+                height: p.size,
+                backgroundColor: p.color,
+                opacity,
+                transform: [{ translateX }, { translateY }, { scale }],
+              },
+            ]}
+          />
+        );
+      })}
+    </>
+  );
+}
+
+export function FireworksOverlay() {
+  const { width, height } = useWindowDimensions();
+
+  const bursts = useMemo<(BurstData & { delay: number })[]>(
+    () =>
+      Array.from({ length: BURST_COUNT }, (_, b) => ({
+        id: b,
+        x: (0.15 + Math.random() * 0.7) * width,
+        y: (0.1 + Math.random() * 0.5) * height,
+        delay: b * 500 + Math.random() * 200,
+        particles: Array.from({ length: PARTICLE_COUNT }, (_, p) => {
+          const angle =
+            (p / PARTICLE_COUNT) * Math.PI * 2 + (Math.random() - 0.5) * 0.2;
+          const dist = 55 + Math.random() * 60;
+          return {
+            id: p,
+            vx: Math.cos(angle) * dist,
+            vy: Math.sin(angle) * dist,
+            color:
+              FIREWORK_COLORS[
+                Math.floor(Math.random() * FIREWORK_COLORS.length)
+              ]!,
+            size: 3 + Math.random() * 3,
+          };
+        }),
+      })),
+    // stable on mount
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+
+  const [mountedBursts, setMountedBursts] = useState<number[]>([]);
+
+  useEffect(() => {
+    const timers = bursts.map((burst, b) =>
+      setTimeout(() => {
+        setMountedBursts((prev) => [...prev, b]);
+      }, burst.delay),
+    );
+    return () => timers.forEach(clearTimeout);
+  }, [bursts]);
+
+  return (
+    <View style={StyleSheet.absoluteFill} pointerEvents="none">
+      {mountedBursts.map((b) => (
+        <FireworkBurst key={b} burst={bursts[b]!} />
+      ))}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  flash: {
+    position: "absolute",
+    width: 12,
+    height: 12,
+    borderRadius: 6,
+    backgroundColor: "#fff",
+  },
+  particle: {
+    position: "absolute",
+    borderRadius: 999,
+  },
+});

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

@@ -2,6 +2,7 @@ import type { Spec } from "@json-render/core";
 import { snapJsonRenderCatalog } from "@farcaster/snap/ui";
 import { SnapCatalogView } from "./catalog-renderer";
 import { ConfettiOverlay } from "./confetti-overlay";
+import { FireworksOverlay } from "./fireworks-overlay";
 import { useSnapTheme } from "./theme";
 import {
   type ReactNode,
@@ -128,10 +129,13 @@ export function SnapViewCoreInner({
   }, [spec]);
 
   const showConfetti = snap.effects?.includes("confetti") ?? false;
+  const showFireworks = snap.effects?.includes("fireworks") ?? false;
   const [confettiKey, setConfettiKey] = useState(0);
+  const [fireworksKey, setFireworksKey] = useState(0);
   useEffect(() => {
     if (showConfetti) setConfettiKey((k) => k + 1);
-  }, [showConfetti, snap]);
+    if (showFireworks) setFireworksKey((k) => k + 1);
+  }, [showConfetti, showFireworks, snap]);
 
   const handlersRef = useRef(handlers);
   handlersRef.current = handlers;
@@ -213,6 +217,7 @@ export function SnapViewCoreInner({
         onAction={handleAction}
       />
       {showConfetti && <ConfettiOverlay key={confettiKey} />}
+      {showFireworks && <FireworksOverlay key={fireworksKey} />}
     </View>
   );
 }

package/src/stack-horizontal-utils.ts

@@ -1,5 +1,7 @@
 import { Children, isValidElement, type ReactNode } from "react";
 
+import { shouldUseHorizontalButtonContent } from "./button-orientation-utils.js";
+
 /**
  * True when every rendered child comes from a catalog `button` element.
  * json-render passes `{ element: { type, props, ... } }` into each catalog component.
@@ -10,32 +12,49 @@ function isRenderableChild(c: ReactNode): boolean {
   return true;
 }
 
-export function horizontalChildrenAreAllButtons(children: ReactNode): boolean {
+export function childrenAreAllButtons(children: ReactNode): boolean {
+  return getButtonChildLabels(children) !== undefined;
+}
+
+export function getButtonChildLabels(children: ReactNode): string[] | undefined {
   const items = Children.toArray(children).filter(isRenderableChild);
-  if (items.length === 0) return false;
+  if (items.length === 0) return undefined;
+  const labels: string[] = [];
   for (const child of items) {
-    if (!isValidElement(child)) return false;
-    const typ = (child.props as { element?: { type?: unknown } }).element?.type;
-    if (typ !== "button") return false;
+    if (!isValidElement(child)) return undefined;
+    const element = (
+      child.props as {
+        element?: { type?: unknown; props?: Record<string, unknown> };
+      }
+    ).element;
+    if (element?.type !== "button") return undefined;
+    labels.push(String(element.props?.label ?? ""));
   }
-  return true;
+  return labels;
+}
+
+export function childrenShouldUseHorizontalButtonLayout(
+  children: ReactNode,
+): boolean | undefined {
+  const labels = getButtonChildLabels(children);
+  return labels ? shouldUseHorizontalButtonContent(labels) : undefined;
 }
 
-/** Direct snap catalog children under a stack (used for all-button grid column count). */
+/** Direct snap catalog children under a stack (used for horizontal gap defaults). */
 export function countRenderableChildren(children: ReactNode): number {
   return Children.toArray(children).filter(isRenderableChild).length;
 }
 
 /**
- * Default horizontal stack gap as a t-shirt size, chosen by column count:
- * 2 cols → lg, 3 cols → md, 4+ cols → sm. Unknown count falls back to md.
+ * Default horizontal stack gap as a t-shirt size, chosen by direct child count:
+ * 2 children → lg, 3 children → md, 4+ children → sm. Unknown count falls back to md.
  * Tighter gaps for denser layouts; authors can always override via the `gap` prop.
  */
 export function defaultHorizontalGapSize(
-  columnCount: number | undefined,
+  childCount: number | undefined,
 ): "sm" | "md" | "lg" {
-  if (columnCount === undefined) return "md";
-  if (columnCount <= 2) return "lg";
-  if (columnCount === 3) return "md";
+  if (childCount === undefined) return "md";
+  if (childCount <= 2) return "lg";
+  if (childCount === 3) return "md";
   return "sm";
 }