@farcaster/snap 2.3.1 → 2.5.0

package/src/ui/catalog.ts

@@ -48,7 +48,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
     toggle_group: {
       props: toggleGroupProps,
       description:
-        "Single or multi-select choice group; `name` becomes POST inputs key. mode: single (default) | multiple. Optional label.",
+        "Single or multi-select choice group; `name` becomes POST inputs key. The @farcaster/snap React/React Native components choose row/column orientation from option label length, ignoring snap-sent orientation hints.",
     },
     input: {
       props: inputProps,
@@ -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) — 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.",
+        "Content row matching shadcn Item: optional media renders on the left, title and optional description render in the content area, and children render in the actions slot (right side). 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,
@@ -92,7 +92,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
     stack: {
       props: stackProps,
       description:
-        "Layout container — direction: vertical (default) | horizontal. Children are element ids in order. Horizontal stacks use a single flex row so peers stay side-by-side and shrink with min-width 0. Nested stacks participate as flexible row peers. All-button horizontal stacks use an equal N-column grid where N is the number of buttons (1–6). Optional `columns` (`2`–`6`) forces an explicit equal grid for mixed children.",
+        "Layout container — direction: vertical (default) | horizontal. Children are element ids in order. Horizontal stacks use a single flex row so peers stay side-by-side and shrink with min-width 0. Nested stacks participate as flexible row peers. For all-button stacks, the @farcaster/snap React/React Native components choose row/column orientation from button label length, ignoring snap-sent direction hints; horizontal button rows use content-proportional widths while filling the container unless `equalWidth: true` is provided to force equal-width cells. Vertical button rows default to a tighter gap when `gap` is omitted.",
     },
     text: {
       props: textProps,
@@ -121,7 +121,8 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
       params: z.object({ target: z.string() }),
     },
     open_snap: {
-      description: "Open a snap URL inline. The client renders the target as a snap rather than opening a browser.",
+      description:
+        "Open a snap URL inline. The client renders the target as a snap rather than opening a browser.",
       params: z.object({ target: z.string() }),
     },
     open_mini_app: {

package/src/ui/cell-grid.ts

@@ -6,6 +6,7 @@ import {
   GRID_MIN_ROWS,
   GRID_MAX_ROWS,
   GRID_GAP_VALUES,
+  GRID_CELL_ASPECT_RATIO_VALUES,
 } from "../constants.js";
 
 /** Palette name or `#rrggbb`; input is trimmed so palette and hex rules match runtime resolvers. */
@@ -13,11 +14,9 @@ const cellGridCellColorSchema = z.preprocess(
   (v) => (typeof v === "string" ? v.trim() : v),
   z.union([
     z.enum(PALETTE_COLOR_VALUES),
-    z
-      .string()
-      .refine(isSnapHexColorString, {
-        message: "cell_grid cell hex color must be #rrggbb",
-      }),
+    z.string().refine(isSnapHexColorString, {
+      message: "cell_grid cell hex color must be #rrggbb",
+    }),
   ]),
 );
 
@@ -36,6 +35,7 @@ export const cellGridProps = z
     rows: z.number().int().min(GRID_MIN_ROWS).max(GRID_MAX_ROWS),
     cells: z.array(cellGridCellSchema),
     gap: z.enum(GRID_GAP_VALUES).optional(),
+    cellAspectRatio: z.enum(GRID_CELL_ASPECT_RATIO_VALUES).optional(),
     rowHeight: z.number().int().min(8).max(64).optional(),
     select: z.enum(["off", "single", "multiple"]).optional(),
   })

package/src/ui/index.ts

@@ -16,8 +16,8 @@ export type { ToggleGroupProps } from "./toggle-group.js";
 export { inputProps } from "./input.js";
 export type { InputProps } from "./input.js";
 
-export { itemProps } from "./item.js";
-export type { ItemProps } from "./item.js";
+export { itemProps, itemMediaProps } from "./item.js";
+export type { ItemMediaProps, ItemProps } from "./item.js";
 
 export { itemGroupProps } from "./item-group.js";
 export type { ItemGroupProps } from "./item-group.js";

package/src/ui/item.ts

@@ -1,13 +1,43 @@
 import { z } from "zod";
+import { PROGRESS_COLOR_VALUES } from "../colors.js";
+import { ICON_NAMES } from "./icon.js";
 
 export const ITEM_VARIANTS = ["default"] as const;
+export const ITEM_MEDIA_VARIANTS = ["icon", "image"] as const;
 export const ITEM_MAX_TITLE_CHARS = 100;
 export const ITEM_MAX_DESCRIPTION_CHARS = 160;
+export const ITEM_MAX_MEDIA_ALT_CHARS = 120;
 
-export const itemProps = z.object({
-  title: z.string().min(1).max(ITEM_MAX_TITLE_CHARS),
-  description: z.string().max(ITEM_MAX_DESCRIPTION_CHARS).optional(),
-  variant: z.enum(ITEM_VARIANTS).optional(),
-});
+const itemIconMediaProps = z
+  .object({
+    variant: z.literal("icon"),
+    name: z.enum(ICON_NAMES),
+    color: z.enum(PROGRESS_COLOR_VALUES).optional(),
+  })
+  .strict();
+
+const itemImageMediaProps = z
+  .object({
+    variant: z.literal("image"),
+    url: z.string(),
+    alt: z.string().max(ITEM_MAX_MEDIA_ALT_CHARS).optional(),
+    round: z.boolean().optional(),
+  })
+  .strict();
+
+export const itemMediaProps = z.discriminatedUnion("variant", [
+  itemIconMediaProps,
+  itemImageMediaProps,
+]);
+
+export const itemProps = z
+  .object({
+    title: z.string().min(1).max(ITEM_MAX_TITLE_CHARS),
+    description: z.string().max(ITEM_MAX_DESCRIPTION_CHARS).optional(),
+    variant: z.enum(ITEM_VARIANTS).optional(),
+    media: itemMediaProps.optional(),
+  })
+  .strict();
 
 export type ItemProps = z.infer<typeof itemProps>;
+export type ItemMediaProps = z.infer<typeof itemMediaProps>;

package/src/ui/stack.ts

@@ -8,7 +8,9 @@ export const stackProps = z.object({
   direction: z.enum(STACK_DIRECTIONS).optional(),
   gap: z.enum(STACK_GAPS).optional(),
   justify: z.enum(STACK_JUSTIFY).optional(),
-  /** Horizontal stacks only: fixed column grid (`2`–`6`). Prefer omitting this when children are stacks — they flex as row peers automatically. */
+  /** Horizontal stacks only: make direct children equal width. */
+  equalWidth: z.boolean().optional(),
+  /** Horizontal stacks only: legacy fixed equal-width column count (`2`–`6`). Prefer `equalWidth`. */
   columns: z.union([
     z.literal(2),
     z.literal(3),

package/src/validator.ts

@@ -29,7 +29,12 @@ const URL_TARGET_ACTIONS = new Set([
  */
 function isLoopback(url: URL): boolean {
   const host = url.hostname;
-  return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+  return (
+    host === "localhost" ||
+    host === "127.0.0.1" ||
+    host === "::1" ||
+    host === "[::1]"
+  );
 }
 
 /**
@@ -84,6 +89,11 @@ type ElementShape = {
   on?: Record<string, { action?: string; params?: Record<string, unknown> }>;
 };
 
+type ItemMediaShape = {
+  variant?: string;
+  url?: unknown;
+};
+
 // ─── Structural validation ────────────────────────────
 
 /**
@@ -169,6 +179,24 @@ function validateUrls(elements: Record<string, unknown>): z.core.$ZodIssue[] {
       }
     }
 
+    if (
+      el.type === "item" &&
+      el.props?.media &&
+      typeof el.props.media === "object"
+    ) {
+      const media = el.props.media as ItemMediaShape;
+      if (media.variant === "image" && typeof media.url === "string") {
+        const error = validateUrl(media.url);
+        if (error) {
+          issues.push({
+            code: "custom",
+            message: error,
+            path: ["ui", "elements", id, "props", "media", "url"],
+          });
+        }
+      }
+    }
+
     // Validate action target URLs
     if (el.on) {
       for (const [event, binding] of Object.entries(el.on)) {