@farcaster/snap 1.3.1 → 1.3.3

package/src/ui/catalog.ts

@@ -0,0 +1,128 @@
+import { defineCatalog } from "@json-render/core";
+import { z } from "zod";
+import { BUTTON_STYLE_VALUES } from "../constants.js";
+import { snapJsonRenderSchema } from "./schema.js";
+import { textProps } from "./text.js";
+import { imageProps } from "./image.js";
+import { dividerProps } from "./divider.js";
+import { spacerProps } from "./spacer.js";
+import { progressProps } from "./progress.js";
+import { listProps } from "./list.js";
+import { gridProps } from "./grid.js";
+import { textInputProps } from "./text-input.js";
+import { sliderProps } from "./slider.js";
+import { buttonGroupProps } from "./button-group.js";
+import { toggleProps } from "./toggle.js";
+import { barChartProps } from "./bar-chart.js";
+import { groupProps } from "./group.js";
+import { stackProps } from "./stack.js";
+import { actionButtonProps } from "./button.js";
+
+const snapPostParams = z.object({
+  buttonIndex: z.number().int().nonnegative(),
+  target: z.string(),
+  label: z.string().optional(),
+  style: z.enum(BUTTON_STYLE_VALUES).optional(),
+});
+
+const snapTargetParams = z.object({
+  target: z.string(),
+});
+
+/**
+ * Basic catalog: one json-render component per snap element type, plus ActionButton for snap buttons.
+ * Does not validate cross-field rules (media count, height budget); snap JSON still goes through `@farcaster/snap` validation.
+ */
+export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
+  components: {
+    Text: {
+      props: textProps,
+      description:
+        "Snap text block — style: title | body | caption | label; optional align.",
+    },
+    Image: {
+      props: imageProps,
+      description: "HTTPS image with fixed aspect ratio.",
+    },
+    Divider: {
+      props: dividerProps,
+      description: "Horizontal rule between blocks.",
+    },
+    Spacer: {
+      props: spacerProps,
+      description: "Vertical whitespace — size small | medium | large.",
+    },
+    Progress: {
+      props: progressProps,
+      description:
+        "Horizontal progress bar (value/max, optional label and color).",
+    },
+    List: {
+      props: listProps,
+      description:
+        "Ordered / unordered / plain list; max 4 items per snap spec.",
+    },
+    Grid: {
+      props: gridProps,
+      description:
+        "Rows×cols cell grid; optional interactive empty cells for games.",
+    },
+    TextInput: {
+      props: textInputProps,
+      description: "Single-line input; `name` becomes POST inputs key.",
+    },
+    Slider: {
+      props: sliderProps,
+      description: "Numeric slider; `name` becomes POST inputs key.",
+    },
+    ButtonGroup: {
+      props: buttonGroupProps,
+      description:
+        "Exclusive choice; `name` and selected option go into POST inputs.",
+    },
+    Toggle: {
+      props: toggleProps,
+      description: "Boolean toggle; `name` becomes POST inputs key.",
+    },
+    BarChart: {
+      props: barChartProps,
+      description:
+        "Vertical bar chart for labeled values — poll results, rankings, breakdowns.",
+    },
+    Group: {
+      props: groupProps,
+      description:
+        "Button row (`layout: row`) or 2-column grid (`layout: grid`); use `children` element ids only (no nested JSON objects).",
+    },
+    Stack: {
+      props: stackProps,
+      description:
+        "Vertical stack for snap page body; maps from snap `page.elements` (`type: stack`). Children are element ids in order top to bottom.",
+    },
+    ActionButton: {
+      props: actionButtonProps,
+      description:
+        "Snap action button: post (next page), link (browser), mini_app, sdk — target is HTTPS URL or SDK id.",
+    },
+  },
+  actions: {
+    snap_post: {
+      description:
+        "POST to snap `target` with signed body (fid, inputs, button_index, timestamp, signature); response is next snap page JSON.",
+      params: snapPostParams,
+    },
+    snap_link: {
+      description: "Open `target` in the system browser; no server round-trip.",
+      params: snapTargetParams,
+    },
+    snap_mini_app: {
+      description: "Open `target` as an in-app Farcaster mini app.",
+      params: snapTargetParams,
+    },
+    snap_sdk: {
+      description:
+        "Run a Farcaster client SDK action (cast:view, user:follow, …).",
+      params: snapTargetParams,
+    },
+  },
+});

package/src/ui/divider.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+
+export const dividerProps = z.object({});
+
+export type DividerProps = z.infer<typeof dividerProps>;

package/src/ui/grid.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import {
+  GRID_CELL_SIZE_VALUES,
+  GRID_GAP_VALUES,
+  HEX_COLOR_6_RE,
+  LIMITS,
+} from "../constants.js";
+
+const gridCellZ = z.object({
+  row: z.number().int().nonnegative(),
+  col: z.number().int().nonnegative(),
+  color: z.string().regex(HEX_COLOR_6_RE).optional(),
+  content: z.string().optional(),
+});
+
+export const gridProps = z.object({
+  cols: z.number().int().min(LIMITS.minGridCols).max(LIMITS.maxGridCols),
+  rows: z.number().int().min(LIMITS.minGridRows).max(LIMITS.maxGridRows),
+  cells: z.array(gridCellZ),
+  cellSize: z.enum(GRID_CELL_SIZE_VALUES).optional(),
+  gap: z.enum(GRID_GAP_VALUES).optional(),
+  interactive: z.boolean().optional(),
+});
+
+export type GridProps = z.infer<typeof gridProps>;

package/src/ui/group.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+
+export const groupProps = z.object({
+  layout: z.enum(["row", "grid"]),
+});
+
+export type GroupProps = z.infer<typeof groupProps>;

package/src/ui/image.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { IMAGE_ASPECT_VALUES } from "../constants.js";
+
+export const imageProps = z.object({
+  url: z.string(),
+  aspect: z.enum(IMAGE_ASPECT_VALUES),
+  alt: z.string().optional(),
+});
+
+export type ImageProps = z.infer<typeof imageProps>;

package/src/ui/index.ts

@@ -0,0 +1,47 @@
+export { snapJsonRenderSchema } from "./schema.js";
+export { snapJsonRenderCatalog } from "./catalog.js";
+
+export { textProps } from "./text.js";
+export type { TextProps } from "./text.js";
+
+export { imageProps } from "./image.js";
+export type { ImageProps } from "./image.js";
+
+export { dividerProps } from "./divider.js";
+export type { DividerProps } from "./divider.js";
+
+export { spacerProps } from "./spacer.js";
+export type { SpacerProps } from "./spacer.js";
+
+export { progressProps } from "./progress.js";
+export type { ProgressProps } from "./progress.js";
+
+export { listProps } from "./list.js";
+export type { ListProps } from "./list.js";
+
+export { gridProps } from "./grid.js";
+export type { GridProps } from "./grid.js";
+
+export { textInputProps } from "./text-input.js";
+export type { TextInputProps } from "./text-input.js";
+
+export { sliderProps } from "./slider.js";
+export type { SliderProps } from "./slider.js";
+
+export { buttonGroupProps } from "./button-group.js";
+export type { ButtonGroupProps } from "./button-group.js";
+
+export { toggleProps } from "./toggle.js";
+export type { ToggleProps } from "./toggle.js";
+
+export { barChartProps } from "./bar-chart.js";
+export type { BarChartProps } from "./bar-chart.js";
+
+export { groupProps } from "./group.js";
+export type { GroupProps } from "./group.js";
+
+export { stackProps } from "./stack.js";
+export type { StackProps } from "./stack.js";
+
+export { actionButtonProps, buttonProps } from "./button.js";
+export type { ActionButtonProps, ButtonProps } from "./button.js";

package/src/ui/list.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { LIMITS, LIST_STYLE_VALUES } from "../constants.js";
+
+const listItemZ = z.object({
+  content: z.string(),
+  trailing: z.string().optional(),
+});
+
+export const listProps = z.object({
+  style: z.enum(LIST_STYLE_VALUES).optional(),
+  items: z
+    .array(listItemZ)
+    .min(LIMITS.minListItems)
+    .max(LIMITS.maxListItems),
+});
+
+export type ListProps = z.infer<typeof listProps>;

package/src/ui/progress.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { PROGRESS_COLOR_VALUES } from "../constants.js";
+
+export const progressProps = z.object({
+  value: z.number(),
+  max: z.number(),
+  label: z.string().optional(),
+  color: z.enum(PROGRESS_COLOR_VALUES).optional(),
+});
+
+export type ProgressProps = z.infer<typeof progressProps>;

package/src/ui/schema.ts

@@ -0,0 +1,37 @@
+import { defineSchema } from "@json-render/core";
+
+/**
+ * json-render spec shape: flat `root` + `elements` map (see [json-render](https://json-render.dev/)).
+ * Component `type` strings must match keys in {@link ./catalog.ts}.
+ */
+export const snapJsonRenderSchema = defineSchema(
+  (s) => ({
+    spec: s.object({
+      root: s.string(),
+      elements: s.record(
+        s.object({
+          type: s.ref("catalog.components"),
+          props: s.propsOf("catalog.components"),
+          children: { ...s.array(s.string()), optional: true },
+        }),
+      ),
+    }),
+    catalog: s.object({
+      components: s.map({
+        props: s.zod(),
+        description: s.string(),
+      }),
+      actions: s.map({
+        description: s.string(),
+        params: { ...s.zod(), optional: true },
+      }),
+    }),
+  }),
+  {
+    defaultRules: [
+      "You are generating auxiliary UI for a Farcaster Snap. Prefer components matching snap element types (Text, Image, ButtonGroup, …).",
+      "Snap pages use a Stack root with at most 5 body children and 1 media element (Image or Grid); keep generated trees small.",
+      "Bottom-of-card snap buttons are ActionButton components; use actions post / link / mini_app / sdk per SPEC.md.",
+    ],
+  },
+);

package/src/ui/slider.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+export const sliderProps = z.object({
+  name: z.string().min(1),
+  min: z.number(),
+  max: z.number(),
+  step: z.number().optional(),
+  value: z.number().optional(),
+  label: z.string().optional(),
+  minLabel: z.string().optional(),
+  maxLabel: z.string().optional(),
+});
+
+export type SliderProps = z.infer<typeof sliderProps>;

package/src/ui/spacer.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import { SPACER_SIZE_VALUES } from "../constants.js";
+
+export const spacerProps = z.object({
+  size: z.enum(SPACER_SIZE_VALUES).optional(),
+});
+
+export type SpacerProps = z.infer<typeof spacerProps>;

package/src/ui/stack.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+
+export const stackProps = z.object({});
+
+export type StackProps = z.infer<typeof stackProps>;

package/src/ui/text-input.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { LIMITS } from "../constants.js";
+
+export const textInputProps = z.object({
+  name: z.string().min(1),
+  placeholder: z.string().optional(),
+  maxLength: z
+    .number()
+    .int()
+    .positive()
+    .max(LIMITS.maxTextInputChars)
+    .optional(),
+});
+
+export type TextInputProps = z.infer<typeof textInputProps>;

package/src/ui/text.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { TEXT_ALIGN_VALUES, TEXT_STYLE_VALUES } from "../constants.js";
+
+export const textProps = z.object({
+  style: z.enum(TEXT_STYLE_VALUES),
+  content: z.string(),
+  align: z.enum(TEXT_ALIGN_VALUES).optional(),
+});
+
+export type TextProps = z.infer<typeof textProps>;

package/src/ui/toggle.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const toggleProps = z.object({
+  name: z.string().min(1),
+  label: z.string(),
+  value: z.boolean().optional(),
+});
+
+export type ToggleProps = z.infer<typeof toggleProps>;

package/src/validator.ts

@@ -1,4 +1,4 @@
-import { z } from "zod/v4";
+import { z } from "zod";
 import {
   BUTTON_GROUP_STYLE,
   DEFAULT_BUTTON_LAYOUT,