@farcaster/snap 2.1.1 → 2.1.2

package/src/constants.ts

@@ -20,7 +20,8 @@ export const GRID_GAP_VALUES = ["none", "sm", "md", "lg"] as const;
 export const MAX_ELEMENTS = 64;
 export const MAX_ROOT_CHILDREN = 7;
 export const MAX_CHILDREN = 6;
-export const MAX_DEPTH = 4;
+/** Enough depth for side-by-side columns that contain labeled horizontal icon rows (pair → column → row → icon). */
+export const MAX_DEPTH = 5;
 
 // ─── Bar chart ─────────────────────────────────────────
 export const BAR_CHART_MAX_BARS = 6;

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

@@ -64,12 +64,16 @@ export function SnapCellGrid({
     });
   }
 
+  /** Cells without a palette `color` — subtle fill so empty slots read as tiles. */
+  const emptyCellBg =
+    colors.mode === "dark" ? "rgba(255, 255, 255, 0.05)" : "rgba(0, 0, 0, 0.05)";
+
   const cellEls: ReactNode[] = [];
   for (let r = 0; r < rows; r++) {
     for (let c = 0; c < cols; c++) {
       const cell = cellMap.get(`${r},${c}`);
       const selected = interactive && isSelected(r, c);
-      const bg = cell?.color ? colors.colorHex(cell.color) : "transparent";
+      const bg = cell?.color ? colors.colorHex(cell.color) : emptyCellBg;
 
       cellEls.push(
         <div
@@ -105,30 +109,19 @@ export function SnapCellGrid({
     }
   }
 
-  const selectionLabel = isSelectable && selectedSet.size > 0
-    ? `inputs.${name}: ${[...selectedSet].join(isMultiple ? " | " : "")}`
-    : null;
-
   return (
-    <div>
-      <div
-        style={{
-          display: "grid",
-          width: "100%",
-          gridTemplateColumns: `repeat(${cols}, 1fr)`,
-          gap: gapPx,
-          padding: 4,
-          borderRadius: 8,
-          backgroundColor: colors.muted,
-        }}
-      >
-        {cellEls}
-      </div>
-      {selectionLabel && (
-        <div className="mt-1.5 truncate text-xs font-mono" style={{ color: colors.textMuted }}>
-          {selectionLabel}
-        </div>
-      )}
+    <div
+      style={{
+        display: "grid",
+        width: "100%",
+        gridTemplateColumns: `repeat(${cols}, 1fr)`,
+        gap: gapPx,
+        padding: 4,
+        borderRadius: 8,
+        backgroundColor: colors.muted,
+      }}
+    >
+      {cellEls}
     </div>
   );
 }

package/src/react/components/image.tsx

@@ -1,6 +1,8 @@
 "use client";
 
 import { AspectRatio } from "@neynar/ui/aspect-ratio";
+import { cn } from "@neynar/ui/utils";
+import { useSnapStackDirection } from "../stack-direction-context";
 
 function aspectToRatio(aspect: string): number {
   const [w, h] = aspect.split(":").map(Number);
@@ -16,11 +18,16 @@ export function SnapImage({
   const url = String(props.url ?? "");
   const alt = String(props.alt ?? "");
   const ratio = aspectToRatio(String(props.aspect ?? "1:1"));
+  const stackDir = useSnapStackDirection();
+  const inHorizontalStack = stackDir === "horizontal";
 
   return (
     <AspectRatio
       ratio={ratio}
-      className="relative w-full flex-1 overflow-hidden rounded-lg"
+      className={cn(
+        "relative overflow-hidden rounded-lg",
+        inHorizontalStack ? "min-w-0 flex-1 basis-0" : "w-full",
+      )}
     >
       {/* eslint-disable-next-line @next/next/no-img-element */}
       <img

package/src/react/components/stack.tsx

@@ -2,6 +2,14 @@
 
 import type { ReactNode } from "react";
 import { cn } from "@neynar/ui/utils";
+import {
+  countRenderableChildren,
+  horizontalChildrenAreAllButtons,
+} from "../../stack-horizontal-utils.js";
+import {
+  SnapStackDirectionProvider,
+  useSnapStackDirection,
+} from "../stack-direction-context";
 
 const VGAP: Record<string, string> = {
   none: "gap-0",
@@ -17,7 +25,7 @@ const HGAP: Record<string, string> = {
   lg: "gap-3",
 };
 
-const JUSTIFY: Record<string, string> = {
+const JUSTIFY_FLEX: Record<string, string> = {
   start: "justify-start",
   center: "justify-center",
   end: "justify-end",
@@ -25,6 +33,16 @@ const JUSTIFY: Record<string, string> = {
   around: "justify-around",
 };
 
+/** Equal columns for explicit `columns` prop and for all-button horizontal rows. */
+const COLUMN_GRID_CLASS: Record<number, string> = {
+  1: "grid grid-cols-1 auto-rows-auto items-stretch [&>*]:min-w-0",
+  2: "grid grid-cols-2 auto-rows-auto items-stretch [&>*]:min-w-0",
+  3: "grid grid-cols-3 auto-rows-auto items-stretch [&>*]:min-w-0",
+  4: "grid grid-cols-4 auto-rows-auto items-stretch [&>*]:min-w-0",
+  5: "grid grid-cols-5 auto-rows-auto items-stretch [&>*]:min-w-0",
+  6: "grid grid-cols-6 auto-rows-auto items-stretch [&>*]:min-w-0",
+};
+
 export function SnapStack({
   element: { props },
   children,
@@ -32,24 +50,79 @@ export function SnapStack({
   element: { props: Record<string, unknown> };
   children?: ReactNode;
 }) {
+  const parentDirection = useSnapStackDirection();
   const direction = String(props.direction ?? "vertical");
   const gapKey = String(props.gap ?? "md");
   const isHorizontal = direction === "horizontal";
   const gap = isHorizontal
     ? (HGAP[gapKey] ?? "gap-2")
     : (VGAP[gapKey] ?? "gap-4");
-  const justify = props.justify ? JUSTIFY[String(props.justify)] : undefined;
+  const justifyKey = props.justify ? String(props.justify) : undefined;
+  const justifyFlex = justifyKey ? JUSTIFY_FLEX[justifyKey] : undefined;
+  const buttonRowGrid =
+    isHorizontal && horizontalChildrenAreAllButtons(children);
+  const buttonRowCount = buttonRowGrid
+    ? countRenderableChildren(children)
+    : 0;
+
+  const columnsRaw = props.columns;
+  const columns =
+    typeof columnsRaw === "number" &&
+    columnsRaw >= 2 &&
+    columnsRaw <= 6 &&
+    Number.isInteger(columnsRaw)
+      ? columnsRaw
+      : undefined;
+  const explicitColumnGrid =
+    isHorizontal && columns !== undefined && !buttonRowGrid;
+  const columnGridClass =
+    explicitColumnGrid && columns !== undefined
+      ? COLUMN_GRID_CLASS[columns]
+      : undefined;
+
+  /**
+   * Row peers under a horizontal stack must shrink and share width (`flex-1` + `min-w-0`).
+   * Avoid `w-full` here: it resolves to 100% of the flex/grid container and fights peer sizing,
+   * so each column stacks on its own wrapped row instead of sitting side-by-side.
+   */
+  const isRowChild = parentDirection === "horizontal";
+  const rootWidthClass = isRowChild
+    ? "min-w-0 flex-1 basis-0 max-w-full"
+    : "w-full min-w-0";
+
+  const justifyBlockGrid =
+    justifyFlex &&
+    (!isHorizontal || (!buttonRowGrid && !explicitColumnGrid));
+
+  /** Single flex row (nowrap): peers stay side-by-side and shrink via min-w-0 / flex-1 on nested stacks. */
+  const horizontalFlexClasses =
+    "flex min-w-0 flex-row flex-nowrap items-stretch [&>*]:min-w-0";
 
   return (
-    <div
-      className={cn(
-        "flex w-full",
-        isHorizontal ? "flex-row items-center flex-wrap" : "flex-col",
-        gap,
-        justify,
-      )}
+    <SnapStackDirectionProvider
+      direction={isHorizontal ? "horizontal" : "vertical"}
     >
-      {children}
-    </div>
+      <div
+        className={cn(
+          rootWidthClass,
+          isHorizontal
+            ? buttonRowGrid &&
+                buttonRowCount >= 1 &&
+                buttonRowCount <= 6 &&
+                COLUMN_GRID_CLASS[buttonRowCount]
+              ? cn(
+                  COLUMN_GRID_CLASS[buttonRowCount]!,
+                  gap,
+                  "[&>*]:w-full",
+                )
+              : explicitColumnGrid && columnGridClass
+                ? cn(columnGridClass, gap)
+                : cn(horizontalFlexClasses, gap, justifyBlockGrid ? justifyFlex : undefined)
+            : cn("flex min-w-0 w-full flex-col", gap, justifyFlex),
+        )}
+      >
+        {children}
+      </div>
+    </SnapStackDirectionProvider>
   );
 }

package/src/react/components/text.tsx

@@ -1,7 +1,9 @@
 "use client";
 
 import { Text } from "@neynar/ui/typography";
+import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors";
+import { useSnapStackDirection } from "../stack-direction-context";
 
 const SIZE_MAP = {
   md: { textSize: "base" as const },
@@ -19,13 +21,18 @@ export function SnapText({
   const align = (props.align as "left" | "center" | "right") ?? undefined;
   const config = SIZE_MAP[size] ?? SIZE_MAP.md;
   const colors = useSnapColors();
+  const stackDir = useSnapStackDirection();
+  const inHorizontalStack = stackDir === "horizontal";
 
   return (
     <Text
       size={config.textSize}
       weight={weight}
       align={align}
-      className="flex-1"
+      className={cn(
+        /** Row peers hug content like RN `wrapRow`; avoid `flex-1` stretching peers across the row. */
+        inHorizontalStack ? "min-w-0 shrink" : "flex-1",
+      )}
       style={{ color: colors.text }}
     >
       {content}

package/src/react/stack-direction-context.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+
+export type SnapStackDirection = "vertical" | "horizontal";
+
+const SnapStackDirectionContext = createContext<SnapStackDirection | undefined>(
+  undefined,
+);
+
+export function SnapStackDirectionProvider({
+  direction,
+  children,
+}: {
+  direction: SnapStackDirection;
+  children: ReactNode;
+}) {
+  return (
+    <SnapStackDirectionContext.Provider value={direction}>
+      {children}
+    </SnapStackDirectionContext.Provider>
+  );
+}
+
+export function useSnapStackDirection(): SnapStackDirection | undefined {
+  return useContext(SnapStackDirectionContext);
+}

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

@@ -66,13 +66,17 @@ export function SnapCellGrid({
   const ringOuter = appearance === "dark" ? "#fff" : "#000";
   const ringInner = appearance === "dark" ? "#000" : "#fff";
 
+  /** Cells without a palette `color` — subtle fill so empty slots read as tiles. */
+  const emptyCellBg =
+    appearance === "dark" ? "rgba(255, 255, 255, 0.05)" : "rgba(0, 0, 0, 0.05)";
+
   const rowEls = [];
   for (let r = 0; r < rows; r++) {
     const rowCells = [];
     for (let c = 0; c < cols; c++) {
       const cell = cellMap.get(`${r},${c}`);
       const selected = interactive && isSelected(r, c);
-      const bg = cell?.color ? hex(cell.color) : "transparent";
+      const bg = cell?.color ? hex(cell.color) : emptyCellBg;
 
       const cellContent = cell?.content ? (
         <Text style={[styles.cellText, { color: colors.textPrimary }]}>
@@ -121,18 +125,9 @@ export function SnapCellGrid({
     );
   }
 
-  const selectionLabel = isSelectable && selectedSet.size > 0
-    ? `inputs.${name}: ${[...selectedSet].join(isMultiple ? " | " : "")}`
-    : null;
-
   return (
     <View style={[styles.wrap, { gap: gapPx, backgroundColor: colors.muted, padding: 4, borderRadius: 8 }]}>
       {rowEls}
-      {selectionLabel ? (
-        <Text style={[styles.selectionText, { color: colors.textSecondary }]}>
-          {selectionLabel}
-        </Text>
-      ) : null}
     </View>
   );
 }
@@ -153,5 +148,4 @@ const styles = StyleSheet.create({
     justifyContent: "center",
   },
   cellText: { fontSize: 12, lineHeight: 16, fontWeight: "600" },
-  selectionText: { fontSize: 11, fontFamily: "monospace", marginTop: 6 },
 });

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

@@ -1,6 +1,7 @@
 import type { ComponentRenderProps } from "@json-render/react-native";
 import { Image } from "expo-image";
 import { StyleSheet, View } from "react-native";
+import { useSnapStackDirection } from "../stack-direction-context";
 
 function aspectToRatio(aspect: string): number {
   const [w, h] = aspect.split(":").map(Number);
@@ -14,9 +15,17 @@ export function SnapImage({
   const url = String(props.url ?? "");
   const alt = String(props.alt ?? "");
   const ratio = aspectToRatio(String(props.aspect ?? "1:1"));
+  const stackDir = useSnapStackDirection();
+  const inHorizontalStack = stackDir === "horizontal";
 
   return (
-    <View style={[styles.frame, { aspectRatio: ratio }]}>
+    <View
+      style={[
+        styles.frame,
+        inHorizontalStack ? styles.frameInHorizontalRow : styles.frameFullWidth,
+        { aspectRatio: ratio },
+      ]}
+    >
       <Image
         source={{ uri: url }}
         style={StyleSheet.absoluteFill}
@@ -29,9 +38,15 @@ export function SnapImage({
 
 const styles = StyleSheet.create({
   frame: {
-    width: "100%",
     borderRadius: 8,
     overflow: "hidden",
     backgroundColor: "#f3f4f6",
   },
+  frameFullWidth: {
+    width: "100%",
+  },
+  frameInHorizontalRow: {
+    flex: 1,
+    minWidth: 0,
+  },
 });

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

@@ -1,6 +1,7 @@
 import type { ComponentRenderProps } from "@json-render/react-native";
 import type { ReactNode } from "react";
 import { StyleSheet, Text, View } from "react-native";
+import { useSnapStackDirection } from "../stack-direction-context";
 import { useSnapTheme } from "../theme";
 
 export function SnapItem({
@@ -12,12 +13,19 @@ export function SnapItem({
   const description = props.description
     ? String(props.description)
     : undefined;
-  const variant = String(props.variant ?? "default");
+  /** Match web `Item className="flex-1"`: row peers must share width or title/description collapse. */
+  const rowPeer = useSnapStackDirection() === "horizontal";
 
   const containerVariant = { paddingVertical: 6, paddingHorizontal: 10 };
 
   return (
-    <View style={[styles.container, containerVariant]}>
+    <View
+      style={[
+        styles.container,
+        containerVariant,
+        rowPeer && styles.rowPeer,
+      ]}
+    >
       <View style={styles.content}>
         {title ? <Text style={[styles.title, { color: colors.text }]}>{title}</Text> : null}
         {description ? (
@@ -40,6 +48,10 @@ const styles = StyleSheet.create({
     flexDirection: "row",
     alignItems: "center",
   },
+  rowPeer: {
+    flex: 1,
+    minWidth: 0,
+  },
   content: {
     flex: 1,
   },

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

@@ -1,5 +1,6 @@
 import type { ComponentRenderProps } from "@json-render/react-native";
 import { StyleSheet, Text, View } from "react-native";
+import { useSnapStackDirection } from "../stack-direction-context";
 import { useSnapPalette } from "../use-snap-palette";
 import { useSnapTheme } from "../theme";
 
@@ -12,9 +13,10 @@ export function SnapProgress({
   const max = Math.max(1, Number(props.max ?? 100));
   const percent = Math.min(100, Math.max(0, (value / max) * 100));
   const label = props.label != null ? String(props.label) : null;
+  const inHorizontalStack = useSnapStackDirection() === "horizontal";
 
   return (
-    <View style={styles.wrap}>
+    <View style={[styles.wrap, inHorizontalStack ? styles.wrapRowPeer : styles.wrapCol]}>
       {label ? (
         <Text style={[styles.label, { color: colors.textSecondary }]}>{label}</Text>
       ) : null}
@@ -26,7 +28,11 @@ export function SnapProgress({
 }
 
 const styles = StyleSheet.create({
-  wrap: { width: "100%", gap: 4 },
+  wrap: { gap: 4 },
+  /** Vertical stacks: span card width (matches web `w-full`). */
+  wrapCol: { width: "100%" },
+  /** Horizontal row peers: share space; `width: 100%` each overflows the row. */
+  wrapRowPeer: { flex: 1, minWidth: 0 },
   label: { fontSize: 13, lineHeight: 18 },
   track: {
     height: 10,

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

@@ -1,6 +1,14 @@
 import type { ComponentRenderProps } from "@json-render/react-native";
-import type { ReactNode } from "react";
+import { Children, type ReactNode } from "react";
 import { StyleSheet, View } from "react-native";
+import {
+  countRenderableChildren,
+  horizontalChildrenAreAllButtons,
+} from "../../stack-horizontal-utils.js";
+import {
+  SnapStackDirectionProvider,
+  useSnapStackDirection,
+} from "../stack-direction-context";
 
 const VGAP: Record<string, number> = {
   none: 0,
@@ -24,10 +32,23 @@ 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. */
+function wrapEqualColumnCells(children: ReactNode): ReactNode {
+  const cells = Children.toArray(children).filter(
+    (c) => c != null && c !== false,
+  );
+  return cells.map((child, i) => (
+    <View key={i} style={styles.equalColumnCell}>
+      {child}
+    </View>
+  ));
+}
+
 export function SnapStack({
   element: { props },
   children,
 }: ComponentRenderProps<Record<string, unknown>> & { children?: ReactNode }) {
+  const parentDirection = useSnapStackDirection();
   const direction = String(props.direction ?? "vertical");
   const rawGap = props.gap;
   const isHorizontal = direction === "horizontal";
@@ -38,29 +59,110 @@ export function SnapStack({
       : typeof rawGap === "string" && rawGap in gapMap
         ? gapMap[rawGap]!
         : isHorizontal ? HGAP.md! : VGAP.md!;
-  const justify = props.justify ? JUSTIFY[String(props.justify)] : undefined;
+  const buttonRowGrid =
+    isHorizontal && horizontalChildrenAreAllButtons(children);
+  const buttonRowCount = buttonRowGrid
+    ? countRenderableChildren(children)
+    : 0;
+
+  const columnsRaw = props.columns;
+  const columns =
+    typeof columnsRaw === "number" &&
+    columnsRaw >= 2 &&
+    columnsRaw <= 6 &&
+    Number.isInteger(columnsRaw)
+      ? columnsRaw
+      : undefined;
+  const explicitColumnGrid =
+    isHorizontal && columns !== undefined && !buttonRowGrid;
+
+  const justify =
+    props.justify &&
+    (!isHorizontal || (!buttonRowGrid && !explicitColumnGrid))
+      ? JUSTIFY[String(props.justify)]
+      : undefined;
+
+  const isRowChild = parentDirection === "horizontal";
+
+  const packedHorizontal =
+    isHorizontal &&
+    ((buttonRowGrid &&
+      buttonRowCount >= 1 &&
+      buttonRowCount <= 6) ||
+      explicitColumnGrid);
+
+  let horizontalBody: ReactNode = children;
+  if (
+    isHorizontal &&
+    buttonRowGrid &&
+    buttonRowCount >= 1 &&
+    buttonRowCount <= 6
+  ) {
+    horizontalBody = wrapEqualColumnCells(children);
+  } else if (isHorizontal && explicitColumnGrid && columns !== undefined) {
+    horizontalBody = wrapEqualColumnCells(children);
+  }
 
   return (
-    <View
-      style={[
-        styles.stack,
-        isHorizontal ? styles.horizontal : undefined,
-        { gap },
-        justify ? { justifyContent: justify } : undefined,
-      ]}
+    <SnapStackDirectionProvider
+      direction={isHorizontal ? "horizontal" : "vertical"}
     >
-      {children}
-    </View>
+      <View
+        style={[
+          isRowChild ? styles.stackRowChild : styles.stack,
+          isHorizontal
+            ? packedHorizontal
+              ? styles.horizontalPacked
+              : styles.horizontalDefault
+            : styles.verticalStack,
+          { gap },
+          justify ? { justifyContent: justify } : undefined,
+        ]}
+      >
+        {horizontalBody}
+      </View>
+    </SnapStackDirectionProvider>
   );
 }
 
 const styles = StyleSheet.create({
   stack: {
     width: "100%",
+    minWidth: 0,
+  },
+  verticalStack: {
+    width: "100%",
+    minWidth: 0,
   },
-  horizontal: {
+  /** Nested stack inside a horizontal row — share width with siblings (matches web flex peers). */
+  stackRowChild: {
+    flexGrow: 1,
+    flexShrink: 1,
+    flexBasis: 0,
+    minWidth: 0,
+    maxWidth: "100%",
+    alignSelf: "stretch",
+  },
+  /** Default horizontal row: single line, equal-height peers. */
+  horizontalDefault: {
     flexDirection: "row",
-    alignItems: "center",
-    flexWrap: "wrap",
+    alignItems: "stretch",
+    flexWrap: "nowrap",
+    width: "100%",
+    minWidth: 0,
+  },
+  /** Single row for packed equal-width cells (button grids & explicit columns). */
+  horizontalPacked: {
+    flexDirection: "row",
+    flexWrap: "nowrap",
+    alignItems: "stretch",
+    width: "100%",
+    minWidth: 0,
+  },
+  equalColumnCell: {
+    flexGrow: 1,
+    flexShrink: 1,
+    flexBasis: 0,
+    minWidth: 0,
   },
 });

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

@@ -1,5 +1,6 @@
 import type { ComponentRenderProps } from "@json-render/react-native";
 import { StyleSheet, Text, View } from "react-native";
+import { useSnapStackDirection } from "../stack-direction-context";
 import { useSnapTheme } from "../theme";
 
 const SIZE_STYLES: Record<string, { fontSize: number; lineHeight?: number; fontWeight?: "400" | "500" | "600" | "700" }> = {
@@ -24,9 +25,10 @@ export function SnapText({
   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";
 
   return (
-    <View style={styles.wrap}>
+    <View style={inHorizontalStack ? styles.wrapRow : styles.wrapCol}>
       <Text
         style={[
           styles.base,
@@ -46,6 +48,9 @@ export function SnapText({
 }
 
 const styles = StyleSheet.create({
-  wrap: { width: "100%" },
+  /** Full width for vertical stacks (alignment / wrapping). */
+  wrapCol: { width: "100%" },
+  /** Row peers: hug content; avoid width 100% fighting nowrap horizontal rows. */
+  wrapRow: { flexShrink: 1, minWidth: 0 },
   base: {},
 });

package/src/react-native/stack-direction-context.tsx

@@ -0,0 +1,25 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+export type SnapStackDirection = "vertical" | "horizontal";
+
+const SnapStackDirectionContext = createContext<SnapStackDirection | undefined>(
+  undefined,
+);
+
+export function SnapStackDirectionProvider({
+  direction,
+  children,
+}: {
+  direction: SnapStackDirection;
+  children: ReactNode;
+}) {
+  return (
+    <SnapStackDirectionContext.Provider value={direction}>
+      {children}
+    </SnapStackDirectionContext.Provider>
+  );
+}
+
+export function useSnapStackDirection(): SnapStackDirection | undefined {
+  return useContext(SnapStackDirectionContext);
+}