@farcaster/snap 2.4.0 → 2.5.1

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

@@ -18,6 +18,7 @@ export function SnapCellGrid({
   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 gap = String(props.gap ?? "sm");
   const gapMap: Record<string, number> = { none: 0, sm: 1, md: 2, lg: 4 };
   const gapPx = gapMap[gap] ?? 1;
@@ -34,11 +35,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,
     });
@@ -91,7 +93,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 }]}>
@@ -101,18 +107,35 @@ export function SnapCellGrid({
 
       // Two-tone ring: outer View with contrasting border, inner View with inverse border
       const cellView = selected ? (
-        <View style={[styles.cell, { height: rowHeight, borderWidth: 1, borderColor: ringOuter, borderRadius: 4 }]}>
+        <View
+          style={[
+            styles.cell,
+            squareCells ? styles.squareCell : { height: rowHeight },
+            { borderWidth: 1, borderColor: ringOuter, borderRadius: 4 },
+          ]}
+        >
           <View
             style={[
               styles.innerCell,
-              { backgroundColor: bg, borderWidth: 1, borderColor: ringInner, borderRadius: 3 },
+              {
+                backgroundColor: bg,
+                borderWidth: 1,
+                borderColor: ringInner,
+                borderRadius: 3,
+              },
             ]}
           >
             {cellContent}
           </View>
         </View>
       ) : (
-        <View style={[styles.cell, { height: rowHeight, backgroundColor: bg }]}>
+        <View
+          style={[
+            styles.cell,
+            squareCells ? styles.squareCell : { height: rowHeight },
+            { backgroundColor: bg },
+          ]}
+        >
           {cellContent}
         </View>
       );
@@ -141,7 +164,17 @@ export function SnapCellGrid({
   }
 
   return (
-    <View style={[styles.wrap, { gap: gapPx, backgroundColor: colors.muted, padding: 4, borderRadius: 8 }]}>
+    <View
+      style={[
+        styles.wrap,
+        {
+          gap: gapPx,
+          backgroundColor: colors.muted,
+          padding: 4,
+          borderRadius: 8,
+        },
+      ]}
+    >
       {rowEls}
     </View>
   );
@@ -156,6 +189,10 @@ const styles = StyleSheet.create({
     alignItems: "center",
     justifyContent: "center",
   },
+  squareCell: {
+    aspectRatio: 1,
+    width: "100%",
+  },
   innerCell: {
     width: "100%",
     height: "100%",

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/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";
 }

package/src/ui/README.md

@@ -41,7 +41,7 @@ Some elements accept a `color` prop:
 
 - `progress` — color name or `"accent"`
 - `bar_chart` — color name or `"accent"` at chart level; color name only per-bar
-- `grid` cells — `#rrggbb` hex
+- `grid` cell fill/text colors — `#rrggbb` hex
 
 When `color` is `"accent"` (or omitted), the element uses the accent color. When it is a specific color name or hex value, that color is **explicit** and independent of `page.theme.accent`.
 

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,
@@ -107,7 +107,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
     cell_grid: {
       props: cellGridProps,
       description:
-        "Cell grid — sparse colored cells on a rows×cols grid. Cell color is a palette name or literal #rrggbb hex (hex ignores page accent). 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.",
+        "Cell grid — sparse colored cells on a rows×cols grid. Cell color and textColor are palette names or literal #rrggbb hex values (hex ignores page accent); textColor overrides the default auto-contrast text color. 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: {
@@ -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,25 +6,25 @@ 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. */
-const cellGridCellColorSchema = z.preprocess(
+const cellGridCellColorSchema = (field: "color" | "textColor") => 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 ${field} hex must be #rrggbb`,
+    }),
   ]),
 );
 
 const cellGridCellSchema = z.object({
   row: z.number().int().nonnegative(),
   col: z.number().int().nonnegative(),
-  color: cellGridCellColorSchema.optional(),
+  color: cellGridCellColorSchema("color").optional(),
+  textColor: cellGridCellColorSchema("textColor").optional(),
   content: z.string().optional(),
   value: z.string().min(1).max(30).optional(),
 });
@@ -36,6 +36,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(),
   })