@farcaster/snap 1.5.1 → 2.0.0

package/src/constants.ts

@@ -1,184 +1,5 @@
-export const POST_GRID_TAP_KEY = "grid_tap" as const;
-
 export const SPEC_VERSION = "1.0" as const;
 
 export const MEDIA_TYPE = "application/vnd.farcaster.snap+json" as const;
 
-export const LIMITS = {
-  maxElementsPerPage: 5,
-  maxButtonsPerPage: 4,
-  maxTextInputChars: 280,
-  maxListItems: 4,
-  minListItems: 1,
-  minButtonGroupOptions: 2,
-  maxButtonGroupOptions: 4,
-  maxButtonGroupOptionChars: 40,
-  maxButtonLabelChars: 30,
-  listItemContentMaxChars: 100,
-  listItemTrailingMaxChars: 40,
-  minGridCols: 2,
-  maxGridCols: 64,
-  minGridRows: 2,
-  maxGridRows: 8,
-  minGroupChildren: 2,
-  maxGroupChildren: 3,
-  maxBarChartBars: 6,
-  barChartLabelMaxChars: 40,
-  maxEstimatedPageHeightPx: 500,
-} as const;
-
-export const TEXT_STYLE = {
-  title: "title",
-  body: "body",
-  caption: "caption",
-  label: "label",
-} as const;
-
-export const TEXT_STYLE_VALUES = [
-  TEXT_STYLE.title,
-  TEXT_STYLE.body,
-  TEXT_STYLE.caption,
-  TEXT_STYLE.label,
-] as const;
-
-export const TEXT_ALIGN_VALUES = ["left", "center", "right"] as const;
-export const IMAGE_ASPECT_VALUES = [
-  "1:1",
-  "16:9",
-  "4:3",
-  "3:4",
-  "9:16",
-] as const;
-
-export const SPACER_SIZE = {
-  small: "small",
-  medium: "medium",
-  large: "large",
-} as const;
-
-export const SPACER_SIZE_VALUES = [
-  SPACER_SIZE.small,
-  SPACER_SIZE.medium,
-  SPACER_SIZE.large,
-] as const;
-
-export const LIST_STYLE_VALUES = ["ordered", "unordered", "plain"] as const;
-
-export const DEFAULT_LIST_STYLE = "ordered" as const;
-
-export const GRID_CELL_SIZE_VALUES = ["auto", "square"] as const;
-export const GRID_GAP_VALUES = ["none", "small", "medium"] as const;
-export const DEFAULT_GRID_GAP =
-  "small" as const satisfies (typeof GRID_GAP_VALUES)[number];
-
-export const BUTTON_GROUP_STYLE = {
-  row: "row",
-  stack: "stack",
-  grid: "grid",
-} as const;
-
-export const BUTTON_GROUP_STYLE_VALUES = [
-  BUTTON_GROUP_STYLE.row,
-  BUTTON_GROUP_STYLE.stack,
-  BUTTON_GROUP_STYLE.grid,
-] as const;
-
-export const BUTTON_ACTION = {
-  post: "post",
-  link: "link",
-  mini_app: "mini_app",
-  client: "client",
-} as const;
-
-export const BUTTON_ACTION_VALUES = [
-  BUTTON_ACTION.post,
-  BUTTON_ACTION.link,
-  BUTTON_ACTION.mini_app,
-  BUTTON_ACTION.client,
-] as const;
-
-export const CLIENT_ACTION = {
-  view_cast: "view_cast",
-  view_profile: "view_profile",
-  compose_cast: "compose_cast",
-  view_token: "view_token",
-  send_token: "send_token",
-  swap_token: "swap_token",
-} as const;
-
-export const CLIENT_ACTION_VALUES = [
-  CLIENT_ACTION.view_cast,
-  CLIENT_ACTION.view_profile,
-  CLIENT_ACTION.compose_cast,
-  CLIENT_ACTION.view_token,
-  CLIENT_ACTION.send_token,
-  CLIENT_ACTION.swap_token,
-] as const;
-
-export const BUTTON_STYLE = {
-  primary: "primary",
-  secondary: "secondary",
-} as const;
-
-export const BUTTON_STYLE_VALUES = [
-  BUTTON_STYLE.primary,
-  BUTTON_STYLE.secondary,
-] as const;
-
-export const BUTTON_LAYOUT_VALUES = ["stack", "row", "grid"] as const;
-export const DEFAULT_BUTTON_LAYOUT = BUTTON_LAYOUT_VALUES[0];
-
 export const EFFECT_VALUES = ["confetti"] as const;
-
-export const GROUP_LAYOUT_VALUES = ["row"] as const;
-
-/** Only valid as `page.elements`: vertical container for the page body (matches json-render trees). */
-export const PAGE_ROOT_TYPE = {
-  stack: "stack",
-} as const;
-
-export const ELEMENT_TYPE = {
-  text: "text",
-  image: "image",
-  divider: "divider",
-  spacer: "spacer",
-  progress: "progress",
-  list: "list",
-  grid: "grid",
-  text_input: "text_input",
-  slider: "slider",
-  button_group: "button_group",
-  toggle: "toggle",
-  group: "group",
-  bar_chart: "bar_chart",
-} as const;
-
-export type ElementType = (typeof ELEMENT_TYPE)[keyof typeof ELEMENT_TYPE];
-
-export const HTTPS_PREFIX = "https://" as const;
-export const HTTP_PREFIX = "http://" as const;
-
-/** 6-digit hex only (#RRGGBB); used for grid cell backgrounds (free hex). */
-export const HEX_COLOR_6_RE = /^#[0-9a-fA-F]{6}$/;
-
-export const TEXT_CONTENT_MAX = {
-  [TEXT_STYLE.title]: 80,
-  [TEXT_STYLE.body]: 160,
-  [TEXT_STYLE.caption]: 100,
-  [TEXT_STYLE.label]: 40,
-} as const satisfies Record<(typeof TEXT_STYLE_VALUES)[number], number>;
-
-export const SLIDER_STEP_ALIGN_EPS = 1e-6;
-export const DEFAULT_SLIDER_STEP = 1 as const;
-
-export const MEDIA_ELEMENT_TYPES = [
-  ELEMENT_TYPE.image,
-  ELEMENT_TYPE.grid,
-] as ElementType[];
-
-export const INTERACTIVE_ELEMENT_TYPES = [
-  ELEMENT_TYPE.button_group,
-  ELEMENT_TYPE.slider,
-  ELEMENT_TYPE.text_input,
-  ELEMENT_TYPE.toggle,
-] as ElementType[];

package/src/dataStore.ts

@@ -0,0 +1,62 @@
+export type DataStoreValue =
+  | string
+  | number
+  | boolean
+  | null
+  | DataStoreValue[]
+  | { [key: string]: DataStoreValue };
+
+export type SnapDataStoreOperations = {
+  get(key: string): Promise<DataStoreValue | null>;
+  set(key: string, value: DataStoreValue): Promise<void>;
+};
+
+export type SnapDataStore = SnapDataStoreOperations & {
+  withLock<T>(fn: (store: SnapDataStoreOperations) => Promise<T>): Promise<T>;
+};
+
+export function createDefaultDataStore(): SnapDataStore {
+  const err = new Error(
+    "Data store is not configured. Use withUpstash() from @farcaster/snap-upstash or provide a data store implementation.",
+  );
+  return {
+    get(_key: string): Promise<never> {
+      return Promise.reject(err);
+    },
+    set(_key: string, _value: DataStoreValue): Promise<never> {
+      return Promise.reject(err);
+    },
+    withLock<T>(
+      _fn: (store: SnapDataStoreOperations) => Promise<T>,
+    ): Promise<never> {
+      return Promise.reject(err);
+    },
+  };
+}
+
+export function createInMemoryDataStore(): SnapDataStore {
+  const data = new Map<string, DataStoreValue>();
+  const ops: SnapDataStoreOperations = {
+    get: async (key: string): Promise<DataStoreValue | null> => {
+      return data.get(key) ?? null;
+    },
+    set: async (key: string, value: DataStoreValue): Promise<void> => {
+      data.set(key, value);
+    },
+  };
+  /** Serializes `withLock` callbacks so async work does not interleave across callers. */
+  let lockChain: Promise<unknown> = Promise.resolve();
+  return {
+    ...ops,
+    withLock<T>(
+      fn: (store: SnapDataStoreOperations) => Promise<T>,
+    ): Promise<T> {
+      const run = lockChain.then(() => fn(ops));
+      lockChain = run.then(
+        () => undefined,
+        () => undefined,
+      );
+      return run;
+    },
+  };
+}

package/src/index.ts

@@ -1,12 +1,8 @@
+export type { Spec as SnapSpec, UIElement as SnapUIElement } from "@json-render/core";
 export {
-  POST_GRID_TAP_KEY,
-  PAGE_ROOT_TYPE,
-  ELEMENT_TYPE,
+  SPEC_VERSION,
   MEDIA_TYPE,
-  DEFAULT_LIST_STYLE,
-  DEFAULT_SLIDER_STEP,
-  CLIENT_ACTION,
-  CLIENT_ACTION_VALUES,
+  EFFECT_VALUES,
 } from "./constants";
 export {
   DEFAULT_THEME_ACCENT,
@@ -21,28 +17,23 @@ export {
   ACTION_TYPE_GET,
   ACTION_TYPE_POST,
   snapResponseSchema,
-  firstPageResponseSchema,
   payloadSchema,
-  clientActionSchema,
-  createDefaultDataStore,
-  type Button,
-  type Element,
-  type Elements,
-  type GroupChildElement,
-  type ClientAction,
   type SnapAction,
-  type SnapPageElementInput,
   type SnapContext,
   type SnapResponse,
   type SnapHandlerResult,
   type SnapFunction,
   type SnapPayload,
-  type DataStoreValue,
-  type SnapDataStore,
-  type SnapDataStoreOperations,
 } from "./schemas";
 export {
   validateSnapResponse,
-  validateFirstPageResponse,
   type ValidationResult,
 } from "./validator";
+export {
+  type DataStoreValue,
+  type SnapDataStore,
+  type SnapDataStoreOperations,
+  createDefaultDataStore,
+  createInMemoryDataStore,
+} from "./dataStore";
+export { type Middleware, useMiddleware } from "./middleware";

package/src/middleware.ts

@@ -0,0 +1,7 @@
+import { SnapFunction } from "./schemas";
+
+export type Middleware = (fn: SnapFunction) => SnapFunction;
+
+export function useMiddleware(fn: SnapFunction, middleware: Middleware[]) {
+  return middleware.reduce((acc, middleware) => middleware(acc), fn);
+}

package/src/react/accent-context.tsx

@@ -0,0 +1,29 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+
+type SnapPreviewAccentContextValue = {
+  /** From loaded snap `page.theme.accent` (undefined if the snap omits it). */
+  pageAccent: string | undefined;
+};
+
+const SnapPreviewAccentContext =
+  createContext<SnapPreviewAccentContextValue | null>(null);
+
+export function SnapPreviewAccentProvider({
+  pageAccent,
+  children,
+}: {
+  pageAccent: string | undefined;
+  children: ReactNode;
+}) {
+  return (
+    <SnapPreviewAccentContext.Provider value={{ pageAccent }}>
+      {children}
+    </SnapPreviewAccentContext.Provider>
+  );
+}
+
+export function useSnapPreviewPageAccent(): string | undefined {
+  return useContext(SnapPreviewAccentContext)?.pageAccent;
+}

package/src/react/catalog-renderer.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import { createRenderer } from "@json-render/react";
+import { snapJsonRenderCatalog } from "@farcaster/snap/ui";
+import { SnapActionButton } from "./components/action-button";
+import { SnapBadge } from "./components/badge";
+import { SnapIcon } from "./components/icon";
+import { SnapImage } from "./components/image";
+import { SnapInput } from "./components/input";
+import { SnapItem } from "./components/item";
+import { SnapItemGroup } from "./components/item-group";
+import { SnapProgress } from "./components/progress";
+import { SnapSeparator } from "./components/separator";
+import { SnapSlider } from "./components/slider";
+import { SnapStack } from "./components/stack";
+import { SnapSwitch } from "./components/switch";
+import { SnapText } from "./components/text";
+import { SnapToggleGroup } from "./components/toggle-group";
+
+/**
+ * Maps snap json-render catalog types to React components.
+ * Keys match the snap wire-format `type` strings exactly.
+ */
+export const SnapCatalogView = createRenderer(snapJsonRenderCatalog, {
+  badge: SnapBadge,
+  button: SnapActionButton,
+  icon: SnapIcon,
+  image: SnapImage,
+  input: SnapInput,
+  item: SnapItem,
+  item_group: SnapItemGroup,
+  progress: SnapProgress,
+  separator: SnapSeparator,
+  slider: SnapSlider,
+  stack: SnapStack,
+  switch: SnapSwitch,
+  text: SnapText,
+  toggle_group: SnapToggleGroup,
+});

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

@@ -0,0 +1,48 @@
+"use client";
+
+import { Button } from "@neynar/ui/button";
+import { cn } from "@neynar/ui/utils";
+import { useSnapAccentScopeStyle } from "../hooks/use-snap-accent";
+import { ICON_MAP } from "./icon";
+
+const VARIANT_MAP: Record<string, "default" | "outline" | "ghost" | "secondary"> = {
+  default: "default",
+  secondary: "secondary",
+  outline: "outline",
+  ghost: "ghost",
+};
+
+export function SnapActionButton({
+  element: { props },
+  emit,
+}: {
+  element: { props: Record<string, unknown> };
+  emit: (name: string) => void;
+}) {
+  const label = String(props.label ?? "Action");
+  const variant = VARIANT_MAP[String(props.variant ?? "default")] ?? "default";
+  const iconName = props.icon ? String(props.icon) : undefined;
+  const accentStyle = useSnapAccentScopeStyle();
+
+  const Icon = iconName ? ICON_MAP[iconName] : undefined;
+
+  return (
+    <div className="w-full min-w-0 flex-1" style={accentStyle}>
+      <Button
+        type="button"
+        variant={variant}
+        className={cn(
+          "w-full gap-2",
+          variant === "default" &&
+            "hover:!bg-[var(--snap-action-primary-hover)]",
+          variant !== "default" &&
+            "hover:!bg-[var(--snap-action-outline-hover)]",
+        )}
+        onClick={() => emit("press")}
+      >
+        {Icon && <Icon size={16} />}
+        {label}
+      </Button>
+    </div>
+  );
+}

package/src/react/components/badge.tsx

@@ -0,0 +1,37 @@
+"use client";
+
+import { Badge } from "@neynar/ui/badge";
+import { useSnapAccentScopeStyle } from "../hooks/use-snap-accent";
+import { ICON_MAP } from "./icon";
+
+export function SnapBadge({
+  element: { props },
+}: {
+  element: { props: Record<string, unknown> };
+}) {
+  const content = String(props.label ?? "");
+  const color = props.color ? String(props.color) : undefined;
+  const iconName = props.icon ? String(props.icon) : undefined;
+  const accentStyle = useSnapAccentScopeStyle();
+
+  const isAccent = !color || color === "accent";
+  const Icon = iconName ? ICON_MAP[iconName] : undefined;
+
+  return (
+    <span style={isAccent ? accentStyle : undefined}>
+      <Badge
+        variant={isAccent ? "default" : "outline"}
+        className="gap-1"
+        // TODO: fix outline badge border color in @neynar/ui — too bright in dark mode
+        style={
+          !isAccent
+            ? { borderColor: `var(--snap-color-${color})`, color: `var(--snap-color-${color})` }
+            : undefined
+        }
+      >
+        {Icon && <Icon size={12} />}
+        {content}
+      </Badge>
+    </span>
+  );
+}

package/src/react/components/icon.tsx

@@ -0,0 +1,115 @@
+"use client";
+
+import {
+  ArrowRight,
+  ArrowLeft,
+  ExternalLink,
+  ChevronRight,
+  Check,
+  X,
+  AlertTriangle,
+  Info,
+  Clock,
+  Heart,
+  MessageCircle,
+  Repeat,
+  Share,
+  User,
+  Users,
+  Star,
+  Trophy,
+  Zap,
+  Flame,
+  Gift,
+  ImageIcon,
+  Play,
+  Pause,
+  Wallet,
+  Coins,
+  Plus,
+  Minus,
+  RefreshCw,
+  Bookmark,
+  ThumbsUp,
+  ThumbsDown,
+  TrendingUp,
+  TrendingDown,
+  type LucideIcon,
+} from "lucide-react";
+import { useSnapAccentScopeStyle } from "../hooks/use-snap-accent";
+
+export const ICON_MAP: Record<string, LucideIcon> = {
+  "arrow-right": ArrowRight,
+  "arrow-left": ArrowLeft,
+  "external-link": ExternalLink,
+  "chevron-right": ChevronRight,
+  check: Check,
+  x: X,
+  "alert-triangle": AlertTriangle,
+  info: Info,
+  clock: Clock,
+  heart: Heart,
+  "message-circle": MessageCircle,
+  repeat: Repeat,
+  share: Share,
+  user: User,
+  users: Users,
+  star: Star,
+  trophy: Trophy,
+  zap: Zap,
+  flame: Flame,
+  gift: Gift,
+  image: ImageIcon,
+  play: Play,
+  pause: Pause,
+  wallet: Wallet,
+  coins: Coins,
+  plus: Plus,
+  minus: Minus,
+  "refresh-cw": RefreshCw,
+  bookmark: Bookmark,
+  "thumbs-up": ThumbsUp,
+  "thumbs-down": ThumbsDown,
+  "trending-up": TrendingUp,
+  "trending-down": TrendingDown,
+};
+
+const SIZE_PX: Record<string, number> = {
+  sm: 16,
+  md: 20,
+};
+
+export function SnapIcon({
+  element: { props },
+}: {
+  element: { props: Record<string, unknown> };
+}) {
+  const name = String(props.name ?? "info");
+  const size = SIZE_PX[String(props.size ?? "md")] ?? 20;
+  const color = props.color ? String(props.color) : undefined;
+  const accentStyle = useSnapAccentScopeStyle();
+
+  const Icon = ICON_MAP[name];
+  if (!Icon) return null;
+
+  const isAccent = !color || color === "accent";
+
+  return (
+    <span
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        ...(isAccent ? accentStyle : {}),
+      }}
+    >
+      <Icon
+        size={size}
+        style={
+          isAccent
+            ? { color: "var(--snap-accent, currentColor)" }
+            : { color: `var(--snap-color-${color}, currentColor)` }
+        }
+      />
+    </span>
+  );
+}

package/src/react/components/image.tsx

@@ -0,0 +1,33 @@
+"use client";
+
+import { AspectRatio } from "@neynar/ui/aspect-ratio";
+
+function aspectToRatio(aspect: string): number {
+  const [w, h] = aspect.split(":").map(Number);
+  if (!w || !h) return 1;
+  return w / h;
+}
+
+export function SnapImage({
+  element: { props },
+}: {
+  element: { props: Record<string, unknown> };
+}) {
+  const url = String(props.url ?? "");
+  const alt = String(props.alt ?? "");
+  const ratio = aspectToRatio(String(props.aspect ?? "1:1"));
+
+  return (
+    <AspectRatio
+      ratio={ratio}
+      className="relative w-full flex-1 overflow-hidden rounded-lg"
+    >
+      {/* eslint-disable-next-line @next/next/no-img-element */}
+      <img
+        src={url}
+        alt={alt}
+        className="absolute inset-0 size-full object-cover"
+      />
+    </AspectRatio>
+  );
+}

package/src/react/components/input.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+import { useId } from "react";
+import { useStateStore } from "@json-render/react";
+import { Input } from "@neynar/ui/input";
+import { Label } from "@neynar/ui/label";
+
+export function SnapInput({
+  element: { props },
+}: {
+  element: { props: Record<string, unknown> };
+}) {
+  const id = useId();
+  const { get, set } = useStateStore();
+  const name = String(props.name ?? "input");
+  const path = `/inputs/${name}`;
+  const label = props.label ? String(props.label) : undefined;
+  const placeholder = props.placeholder ? String(props.placeholder) : undefined;
+  const maxLength =
+    typeof props.maxLength === "number" ? props.maxLength : undefined;
+  const raw = get(path);
+  const value = typeof raw === "string" ? raw : "";
+
+  return (
+    <div className="w-full space-y-1.5">
+      {label && <Label htmlFor={id}>{label}</Label>}
+      <Input
+        id={id}
+        value={value}
+        onChange={(e) => set(path, e.target.value)}
+        placeholder={placeholder}
+        maxLength={maxLength}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,43 @@
+"use client";
+
+import { Children, type ReactNode, Fragment } from "react";
+import { cn } from "@neynar/ui/utils";
+
+const GAP_MAP: Record<string, string> = {
+  none: "gap-0",
+  sm: "gap-1",
+  md: "gap-2",
+  lg: "gap-3",
+};
+
+export function SnapItemGroup({
+  element: { props },
+  children,
+}: {
+  element: { props: Record<string, unknown> };
+  children?: ReactNode;
+}) {
+  const border = Boolean(props.border);
+  const separator = Boolean(props.separator);
+  const gap = GAP_MAP[String(props.gap ?? "sm")] ?? "gap-1";
+  const items = Children.toArray(children);
+
+  return (
+    <div
+      className={cn(
+        "flex flex-col",
+        border && "rounded-lg border",
+        gap,
+      )}
+    >
+      {items.map((child, i) => (
+        <Fragment key={i}>
+          {separator && i > 0 && (
+            <div className="h-px bg-border" />
+          )}
+          {child}
+        </Fragment>
+      ))}
+    </div>
+  );
+}