@farcaster/snap 2.3.0 → 2.3.1

package/dist/colors.d.ts

@@ -34,6 +34,14 @@ export declare function resolveSnapColorHex(color: string | undefined, opts: {
     accentHex: string;
     appearance: "light" | "dark";
 }): string;
+/**
+ * Pick a readable text color for a given hex background.
+ *
+ * Uses WCAG relative luminance with a 0.5 threshold. Returns `rgba(...)` so
+ * callers can soften the text against the background — defaults to 0.8 alpha
+ * to let a hint of the cell color bleed through.
+ */
+export declare function readableTextOnHex(hex: string, alpha?: number): string;
 /** Light-mode hex for each palette color (emulator / reference client). */
 export declare const PALETTE_LIGHT_HEX: Record<PaletteColor, string>;
 /** Dark-mode hex for each palette color (reference). */

package/dist/colors.js

@@ -54,6 +54,27 @@ export function resolveSnapColorHex(color, opts) {
     }
     return opts.accentHex;
 }
+/**
+ * Pick a readable text color for a given hex background.
+ *
+ * Uses WCAG relative luminance with a 0.5 threshold. Returns `rgba(...)` so
+ * callers can soften the text against the background — defaults to 0.8 alpha
+ * to let a hint of the cell color bleed through.
+ */
+export function readableTextOnHex(hex, alpha = 0.8) {
+    const m = /^#([0-9a-fA-F]{6})$/.exec(hex.trim());
+    if (!m)
+        return `rgba(0,0,0,${alpha})`;
+    const n = Number.parseInt(m[1], 16);
+    const toLin = (c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    };
+    const L = 0.2126 * toLin((n >> 16) & 0xff) +
+        0.7152 * toLin((n >> 8) & 0xff) +
+        0.0722 * toLin(n & 0xff);
+    return L >= 0.5 ? `rgba(0,0,0,${alpha})` : `rgba(255,255,255,${alpha})`;
+}
 /** Light-mode hex for each palette color (emulator / reference client). */
 export const PALETTE_LIGHT_HEX = {
     gray: "#6E6A86",

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { Spec as SnapSpec, UIElement as SnapUIElement, } from "@json-render/core";
 export { SPEC_VERSION, SPEC_VERSION_1, SPEC_VERSION_2, SUPPORTED_SPEC_VERSIONS, type SpecVersion, SNAP_PAYLOAD_HEADER, MEDIA_TYPE, EFFECT_VALUES, POST_GRID_TAP_KEY, MAX_ELEMENTS, MAX_ROOT_CHILDREN, MAX_CHILDREN, MAX_DEPTH, } from "./constants.js";
-export { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, isSnapHexColorString, resolveSnapColorHex, type PaletteColor, } from "./colors.js";
+export { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, isSnapHexColorString, readableTextOnHex, resolveSnapColorHex, type PaletteColor, } from "./colors.js";
 export { ACTION_TYPE_GET, ACTION_TYPE_POST, snapResponseSchema, payloadSchema, getPayloadSchema, type SnapAction, type SnapGetAction, type SnapContext, type SnapResponse, type SnapHandlerResult, type SnapElementInput, type SnapSpecInput, type SnapFunction, type SnapPayload, type SnapGetPayload, } from "./schemas.js";
 export { validateSnapResponse, type ValidationResult } from "./validator.js";

package/dist/index.js

@@ -1,4 +1,4 @@
 export { SPEC_VERSION, SPEC_VERSION_1, SPEC_VERSION_2, SUPPORTED_SPEC_VERSIONS, SNAP_PAYLOAD_HEADER, MEDIA_TYPE, EFFECT_VALUES, POST_GRID_TAP_KEY, MAX_ELEMENTS, MAX_ROOT_CHILDREN, MAX_CHILDREN, MAX_DEPTH, } from "./constants.js";
-export { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, isSnapHexColorString, resolveSnapColorHex, } from "./colors.js";
+export { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, isSnapHexColorString, readableTextOnHex, resolveSnapColorHex, } from "./colors.js";
 export { ACTION_TYPE_GET, ACTION_TYPE_POST, snapResponseSchema, payloadSchema, getPayloadSchema, } from "./schemas.js";
 export { validateSnapResponse } from "./validator.js";

package/dist/react/components/action-button.js

@@ -5,6 +5,7 @@ import { ExternalLink } from "lucide-react";
 import { Button } from "@neynar/ui/button";
 import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors.js";
+import { useSnapStackDirection } from "../stack-direction-context.js";
 import { ICON_MAP } from "./icon.js";
 function isExternalLinkAction(on) {
     if (!on)
@@ -24,6 +25,7 @@ export function SnapActionButton({ element, emit, }) {
     const [hovered, setHovered] = useState(false);
     const Icon = iconName ? ICON_MAP[iconName] : undefined;
     const showExternalIcon = isExternalLinkAction(element.on);
+    const inHorizontalStack = useSnapStackDirection() === "horizontal";
     const style = {
         cursor: "pointer",
         ...(isPrimary
@@ -40,5 +42,13 @@ export function SnapActionButton({ element, emit, }) {
                 borderColor: "transparent",
             }),
     };
-    return (_jsx("div", { className: "w-full min-w-0 flex-1", children: _jsxs(Button, { type: "button", variant: isPrimary ? "default" : "secondary", className: cn("w-full gap-2"), style: style, onClick: () => emit("press"), onPointerEnter: () => setHovered(true), onPointerLeave: () => setHovered(false), children: [Icon && _jsx(Icon, { size: 16 }), label, showExternalIcon && (_jsx(ExternalLink, { size: 14, style: { opacity: 0.6 } }))] }) }));
+    return (
+    /**
+     * In a horizontal stack, `flex-1` lets the wrapper share row width with peers.
+     * In a vertical stack, `flex-1` would silently grow the button to fill column
+     * height (1/N distribution when siblings also flex-grow); stick to `w-full`.
+     */
+    _jsx("div", { className: inHorizontalStack
+            ? "w-full min-w-0 flex-1"
+            : "w-full min-w-0", children: _jsxs(Button, { type: "button", variant: isPrimary ? "default" : "secondary", className: cn("w-full gap-2"), style: style, onClick: () => emit("press"), onPointerEnter: () => setHovered(true), onPointerLeave: () => setHovered(false), children: [Icon && _jsx(Icon, { size: 16 }), label, showExternalIcon && (_jsx(ExternalLink, { size: 14, style: { opacity: 0.6 } }))] }) }));
 }

package/dist/react/components/cell-grid.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useStateStore } from "@json-render/react";
 import { cn } from "@neynar/ui/utils";
-import { POST_GRID_TAP_KEY } from "@farcaster/snap";
+import { POST_GRID_TAP_KEY, readableTextOnHex } from "@farcaster/snap";
 import { useSnapColors } from "../hooks/use-snap-colors.js";
 export function SnapCellGrid({ element: { props, on }, emit, }) {
     const { get, set } = useStateStore();
@@ -69,7 +69,9 @@ export function SnapCellGrid({ element: { props, on }, emit, }) {
         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) : emptyCellBg;
+            const bgHex = cell?.color ? colors.colorHex(cell.color) : null;
+            const bg = bgHex ?? emptyCellBg;
+            const textColor = bgHex ? readableTextOnHex(bgHex) : colors.text;
             cellEls.push(_jsx("div", { role: interactive ? "button" : undefined, tabIndex: interactive ? 0 : undefined, onClick: interactive ? () => handleTap(r, c) : undefined, onKeyDown: interactive
                     ? (e) => {
                         if (e.key === "Enter" || e.key === " ") {
@@ -80,6 +82,7 @@ export function SnapCellGrid({ element: { props, on }, emit, }) {
                     : undefined, className: cn("flex items-center justify-center rounded text-xs font-semibold", interactive ? "cursor-pointer select-none" : "cursor-default"), style: {
                     height: rowHeight,
                     background: bg,
+                    color: textColor,
                     boxShadow: selected
                         ? `inset 0 0 0 1px ${colors.mode === "dark" ? "#000" : "#fff"}, inset 0 0 0 2px ${colors.mode === "dark" ? "#fff" : "#000"}`
                         : undefined,

package/dist/react/components/item.js

@@ -1,10 +1,15 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions, } from "@neynar/ui/item";
+import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors.js";
+import { useSnapStackDirection } from "../stack-direction-context.js";
 export function SnapItem({ element: { props, children: childIds }, children, }) {
     const title = String(props.title ?? "");
     const description = props.description ? String(props.description) : undefined;
     const colors = useSnapColors();
-    return (_jsxs(Item, { className: "flex-1 py-1.5 px-2.5", children: [_jsxs(ItemContent, { className: "gap-0.5", children: [_jsx(ItemTitle, { style: { color: colors.text }, children: title }), description && (_jsx(ItemDescription, { className: "mt-0", style: { color: colors.textMuted }, children: description }))] }), childIds && childIds.length > 0 && _jsx(ItemActions, { children: children })] }));
+    const inHorizontalStack = useSnapStackDirection() === "horizontal";
+    return (_jsxs(Item, { className: cn("py-1.5 px-2.5", 
+        /** Horizontal: share width with peers. Vertical: don't fill column height. */
+        inHorizontalStack && "flex-1"), children: [_jsxs(ItemContent, { className: "gap-0.5", children: [_jsx(ItemTitle, { style: { color: colors.text }, children: title }), description && (_jsx(ItemDescription, { className: "mt-0", style: { color: colors.textMuted }, children: description }))] }), childIds && childIds.length > 0 && _jsx(ItemActions, { children: children })] }));
 }

package/dist/react/components/progress.js

@@ -1,11 +1,16 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors.js";
+import { useSnapStackDirection } from "../stack-direction-context.js";
 export function SnapProgress({ element: { props }, }) {
     const colors = useSnapColors();
     const value = Number(props.value ?? 0);
     const max = Math.max(1, Number(props.max ?? 100));
     const percent = Math.min(100, Math.max(0, (value / max) * 100));
     const label = props.label ? String(props.label) : null;
-    return (_jsxs("div", { className: "flex w-full flex-1 flex-col gap-1", children: [label && (_jsx("span", { className: "text-xs", style: { color: colors.textMuted }, children: label })), _jsx("div", { className: "h-2.5 w-full overflow-hidden rounded-full", style: { backgroundColor: colors.muted }, children: _jsx("div", { className: "h-full rounded-full transition-all", style: { width: `${percent}%`, backgroundColor: colors.accent } }) })] }));
+    const inHorizontalStack = useSnapStackDirection() === "horizontal";
+    return (_jsxs("div", { className: cn("flex w-full flex-col gap-1", 
+        /** Horizontal: share width with peers. Vertical: don't fill column height. */
+        inHorizontalStack && "flex-1"), children: [label && (_jsx("span", { className: "text-xs", style: { color: colors.textMuted }, children: label })), _jsx("div", { className: "h-2.5 w-full overflow-hidden rounded-full", style: { backgroundColor: colors.muted }, children: _jsx("div", { className: "h-full rounded-full transition-all", style: { width: `${percent}%`, backgroundColor: colors.accent } }) })] }));
 }

package/dist/react-native/components/snap-cell-grid.js

@@ -3,7 +3,7 @@ import { StyleSheet, Text, View, Pressable } from "react-native";
 import { useStateStore } from "@json-render/react-native";
 import { useSnapPalette } from "../use-snap-palette.js";
 import { useSnapTheme } from "../theme.js";
-import { POST_GRID_TAP_KEY } from "@farcaster/snap";
+import { POST_GRID_TAP_KEY, readableTextOnHex } from "@farcaster/snap";
 export function SnapCellGrid({ element, emit, }) {
     const { props } = element;
     const on = element.on;
@@ -75,8 +75,10 @@ export function SnapCellGrid({ element, emit, }) {
         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) : emptyCellBg;
-            const cellContent = cell?.content ? (_jsx(Text, { style: [styles.cellText, { color: colors.textPrimary }], children: cell.content })) : null;
+            const bgHex = cell?.color ? hex(cell.color) : null;
+            const bg = bgHex ?? emptyCellBg;
+            const textColor = bgHex ? readableTextOnHex(bgHex) : colors.text;
+            const cellContent = cell?.content ? (_jsx(Text, { style: [styles.cellText, { color: textColor }], children: cell.content })) : null;
             // Two-tone ring: outer View with contrasting border, inner View with inverse border
             const cellView = selected ? (_jsx(View, { style: [styles.cell, { height: rowHeight, borderWidth: 1, borderColor: ringOuter, borderRadius: 4 }], children: _jsx(View, { style: [
                         styles.innerCell,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farcaster/snap",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Farcaster Snaps 🫰",
   "repository": {
     "type": "git",

package/src/colors.ts

@@ -65,6 +65,28 @@ export function resolveSnapColorHex(
   return opts.accentHex;
 }
 
+/**
+ * Pick a readable text color for a given hex background.
+ *
+ * Uses WCAG relative luminance with a 0.5 threshold. Returns `rgba(...)` so
+ * callers can soften the text against the background — defaults to 0.8 alpha
+ * to let a hint of the cell color bleed through.
+ */
+export function readableTextOnHex(hex: string, alpha = 0.8): string {
+  const m = /^#([0-9a-fA-F]{6})$/.exec(hex.trim());
+  if (!m) return `rgba(0,0,0,${alpha})`;
+  const n = Number.parseInt(m[1], 16);
+  const toLin = (c: number) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  const L =
+    0.2126 * toLin((n >> 16) & 0xff) +
+    0.7152 * toLin((n >> 8) & 0xff) +
+    0.0722 * toLin(n & 0xff);
+  return L >= 0.5 ? `rgba(0,0,0,${alpha})` : `rgba(255,255,255,${alpha})`;
+}
+
 /** Light-mode hex for each palette color (emulator / reference client). */
 export const PALETTE_LIGHT_HEX: Record<PaletteColor, string> = {
   gray: "#6E6A86",

package/src/index.ts

@@ -25,6 +25,7 @@ export {
   PALETTE_LIGHT_HEX,
   PALETTE_DARK_HEX,
   isSnapHexColorString,
+  readableTextOnHex,
   resolveSnapColorHex,
   type PaletteColor,
 } from "./colors";

package/src/react/components/action-button.tsx

@@ -5,6 +5,7 @@ import { ExternalLink } from "lucide-react";
 import { Button } from "@neynar/ui/button";
 import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors";
+import { useSnapStackDirection } from "../stack-direction-context";
 import { ICON_MAP } from "./icon";
 
 function isExternalLinkAction(
@@ -38,6 +39,7 @@ export function SnapActionButton({
 
   const Icon = iconName ? ICON_MAP[iconName] : undefined;
   const showExternalIcon = isExternalLinkAction(element.on);
+  const inHorizontalStack = useSnapStackDirection() === "horizontal";
 
   const style = {
     cursor: "pointer" as const,
@@ -57,7 +59,18 @@ export function SnapActionButton({
   };
 
   return (
-    <div className="w-full min-w-0 flex-1">
+    /**
+     * In a horizontal stack, `flex-1` lets the wrapper share row width with peers.
+     * In a vertical stack, `flex-1` would silently grow the button to fill column
+     * height (1/N distribution when siblings also flex-grow); stick to `w-full`.
+     */
+    <div
+      className={
+        inHorizontalStack
+          ? "w-full min-w-0 flex-1"
+          : "w-full min-w-0"
+      }
+    >
       <Button
         type="button"
         variant={isPrimary ? "default" : "secondary"}

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

@@ -3,7 +3,7 @@
 import type { ReactNode } from "react";
 import { useStateStore } from "@json-render/react";
 import { cn } from "@neynar/ui/utils";
-import { POST_GRID_TAP_KEY } from "@farcaster/snap";
+import { POST_GRID_TAP_KEY, readableTextOnHex } from "@farcaster/snap";
 import { useSnapColors } from "../hooks/use-snap-colors";
 
 export function SnapCellGrid({
@@ -85,7 +85,9 @@ export function SnapCellGrid({
     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) : emptyCellBg;
+      const bgHex = cell?.color ? colors.colorHex(cell.color) : null;
+      const bg = bgHex ?? emptyCellBg;
+      const textColor = bgHex ? readableTextOnHex(bgHex) : colors.text;
 
       cellEls.push(
         <div
@@ -110,6 +112,7 @@ export function SnapCellGrid({
           style={{
             height: rowHeight,
             background: bg,
+            color: textColor,
             boxShadow: selected
               ? `inset 0 0 0 1px ${colors.mode === "dark" ? "#000" : "#fff"}, inset 0 0 0 2px ${colors.mode === "dark" ? "#fff" : "#000"}`
               : undefined,

package/src/react/components/item.tsx

@@ -7,7 +7,9 @@ import {
   ItemDescription,
   ItemActions,
 } from "@neynar/ui/item";
+import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors";
+import { useSnapStackDirection } from "../stack-direction-context";
 
 export function SnapItem({
   element: { props, children: childIds },
@@ -19,9 +21,16 @@ export function SnapItem({
   const title = String(props.title ?? "");
   const description = props.description ? String(props.description) : undefined;
   const colors = useSnapColors();
+  const inHorizontalStack = useSnapStackDirection() === "horizontal";
 
   return (
-    <Item className="flex-1 py-1.5 px-2.5">
+    <Item
+      className={cn(
+        "py-1.5 px-2.5",
+        /** Horizontal: share width with peers. Vertical: don't fill column height. */
+        inHorizontalStack && "flex-1",
+      )}
+    >
       <ItemContent className="gap-0.5">
         <ItemTitle style={{ color: colors.text }}>{title}</ItemTitle>
         {description && (

package/src/react/components/progress.tsx

@@ -1,6 +1,8 @@
 "use client";
 
+import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors";
+import { useSnapStackDirection } from "../stack-direction-context";
 
 export function SnapProgress({
   element: { props },
@@ -12,9 +14,16 @@ 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 ? String(props.label) : null;
+  const inHorizontalStack = useSnapStackDirection() === "horizontal";
 
   return (
-    <div className="flex w-full flex-1 flex-col gap-1">
+    <div
+      className={cn(
+        "flex w-full flex-col gap-1",
+        /** Horizontal: share width with peers. Vertical: don't fill column height. */
+        inHorizontalStack && "flex-1",
+      )}
+    >
       {label && (
         <span className="text-xs" style={{ color: colors.textMuted }}>
           {label}

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

@@ -3,7 +3,7 @@ import { StyleSheet, Text, View, Pressable } from "react-native";
 import { useStateStore } from "@json-render/react-native";
 import { useSnapPalette } from "../use-snap-palette";
 import { useSnapTheme } from "../theme";
-import { POST_GRID_TAP_KEY } from "@farcaster/snap";
+import { POST_GRID_TAP_KEY, readableTextOnHex } from "@farcaster/snap";
 
 export function SnapCellGrid({
   element,
@@ -89,10 +89,12 @@ export function SnapCellGrid({
     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) : emptyCellBg;
+      const bgHex = cell?.color ? hex(cell.color) : null;
+      const bg = bgHex ?? emptyCellBg;
+      const textColor = bgHex ? readableTextOnHex(bgHex) : colors.text;
 
       const cellContent = cell?.content ? (
-        <Text style={[styles.cellText, { color: colors.textPrimary }]}>
+        <Text style={[styles.cellText, { color: textColor }]}>
           {cell.content}
         </Text>
       ) : null;