chore: define handler for frame launching

Author: michalkvasnicak

packages/render/src/ui/frame.base.tsx

@@ -7,7 +7,7 @@ import {
   useState,
 } from "react";
 import type { FrameState } from "../types";
-import type { UseFrameReturnValue } from "../unstable-types";
+import type { PartialFrameV2, UseFrameReturnValue } from "../unstable-types";
 import { useFreshRef } from "../hooks/use-fresh-ref";
 import type {
   FrameMessage,
@@ -17,7 +17,6 @@ import type {
   RootContainerDimensions,
   RootContainerElement,
   FrameButtonProps,
-  PartialFrameV2,
 } from "./types";
 import {
   getErrorMessageFromFramesStackItem,
@@ -30,7 +29,7 @@ export type FrameUIComponents<TStylingProps extends Record<string, unknown>> =
 export type FrameUITheme<TStylingProps extends Record<string, unknown>> =
   Partial<FrameUIComponentStylingProps<TStylingProps>>;
 
-export type AppLaunchButtonPressEvent =
+export type FrameUILaunchFrameButtonPressEvent =
   | {
       status: "complete";
       frame: FrameV2;
@@ -42,6 +41,10 @@ export type AppLaunchButtonPressEvent =
       frameUIState: FrameUIState;
     };
 
+export type FrameUILaunchFrameButtonPressHandler = (
+  event: FrameUILaunchFrameButtonPressEvent
+) => void;
+
 export type BaseFrameUIProps<TStylingProps extends Record<string, unknown>> = {
   frameState:
     | FrameState<any, any>
@@ -81,13 +84,13 @@ export type BaseFrameUIProps<TStylingProps extends Record<string, unknown>> = {
    *
    * Only Frames v2 support this feature.
    */
-  onAppLaunchButtonPress?: (event: AppLaunchButtonPressEvent) => void;
+  onLaunchFrameButtonPress?: FrameUILaunchFrameButtonPressHandler;
   /**
    * Called when an error occurs in onAppLaunchButtonPress
    *
    * @defaultValue console.error()
    */
-  onAppLaunchButtonPressError?: (error: Error) => void;
+  onLaunchFrameButtonPressError?: (error: Error) => void;
 };
 
 // eslint-disable-next-line @typescript-eslint/no-empty-function -- this is noop
@@ -113,19 +116,20 @@ export function BaseFrameUI<TStylingProps extends Record<string, unknown>>({
   allowPartialFrame = false,
   enableImageDebugging = false,
   onError = defaultErrorLogger,
-  onAppLaunchButtonPressError = defaultErrorLogger,
+  onLaunchFrameButtonPressError = defaultErrorLogger,
   onMessage = defaultMessageHandler,
   createElement = reactCreateElement,
-  onAppLaunchButtonPress = defaultOnAppLaunchButtonPress,
+  onLaunchFrameButtonPress = defaultOnAppLaunchButtonPress,
 }: BaseFrameUIProps<TStylingProps>): JSX.Element | null {
   const [isImageLoading, setIsImageLoading] = useState(true);
   const { currentFrameStackItem } = frameState;
   const rootRef = useRef<RootContainerElement>(null);
   const rootDimensionsRef = useRef<RootContainerDimensions | undefined>();
   const onErrorRef = useFreshRef(onError);
-  const onAppLaunchButtonPressErrorRef = useFreshRef(
-    onAppLaunchButtonPressError
+  const onLaunchFrameButtonPressErrorRef = useFreshRef(
+    onLaunchFrameButtonPressError
   );
+  const onLaunchFrameButtonPressRef = useFreshRef(onLaunchFrameButtonPress);
 
   const onImageLoadEnd = useCallback(() => {
     setIsImageLoading(false);
@@ -340,7 +344,27 @@ export function BaseFrameUI<TStylingProps extends Record<string, unknown>>({
           onPress() {
             // we don't need to track dimensions here because this button does nothing to frame stack
             try {
-              onAppLaunchButtonPress(
+              if (!("onLaunchFrameButtonPress" in frameState)) {
+                throw new Error(
+                  "onLaunchFrameButtonPress is not implemented, you are porbably using old useFrame hook"
+                );
+              }
+
+              // call onLaunchFrameButtonPress on useFrame() hook
+              // because that's where the core of the frame v2 message handling is implemented
+              frameState.onLaunchFrameButtonPress(
+                frameUiState.status === "complete"
+                  ? {
+                      status: "complete",
+                      frame: frameUiState.frame,
+                    }
+                  : {
+                      status: "partial",
+                      frame: frameUiState.frame,
+                    }
+              );
+
+              onLaunchFrameButtonPressRef.current(
                 frameUiState.status === "complete"
                   ? {
                       status: "complete",
@@ -354,7 +378,7 @@ export function BaseFrameUI<TStylingProps extends Record<string, unknown>>({
                     }
               );
             } catch (e) {
-              onAppLaunchButtonPressErrorRef.current(
+              onLaunchFrameButtonPressErrorRef.current(
                 e instanceof Error ? e : new Error(String(e))
               );
             }

packages/render/src/ui/types.ts

@@ -1,8 +1,7 @@
 import type { Frame, FrameButton, FrameV2 } from "frames.js";
 import type { createElement, ReactElement } from "react";
-import type { ParsedFrameV2 } from "frames.js/frame-parsers";
 import type { FrameState } from "../types";
-import type { UseFrameReturnValue } from "../unstable-types";
+import type { PartialFrameV2, UseFrameReturnValue } from "../unstable-types";
 
 /**
  * Allows to override styling props on all component of the Frame UI
@@ -31,26 +30,6 @@ type RequiredFrameProperties = "image" | "buttons";
 export type PartialFrame = Omit<Partial<Frame>, RequiredFrameProperties> &
   Required<Pick<Frame, RequiredFrameProperties>>;
 
-/**
- * If partial frame rendering is enabled this is the shape of the frame
- */
-export type PartialFrameV2 = Omit<ParsedFrameV2, "imageUrl" | "button"> & {
-  imageUrl: NonNullable<ParsedFrameV2["imageUrl"]>;
-  button: Omit<NonNullable<ParsedFrameV2["button"]>, "action" | "title"> & {
-    action: Omit<
-      NonNullable<NonNullable<ParsedFrameV2["button"]>["action"]>,
-      "url" | "title"
-    > & {
-      url: NonNullable<
-        NonNullable<NonNullable<ParsedFrameV2["button"]>["action"]>["url"]
-      >;
-    };
-    title: NonNullable<
-      NonNullable<NonNullable<ParsedFrameV2["button"]>["title"]>
-    >;
-  };
-};
-
 type FrameUIStateLoading = {
   status: "loading";
   id: number;

packages/render/src/ui/utils.ts

@@ -6,11 +6,12 @@ import type {
   FrameStackRequestError,
 } from "../types";
 import type {
+  PartialFrameV2,
   FramesStackItem as UnstableFramesStackItem,
   FrameStackMessage as UnstableFrameStackMessage,
   FrameStackRequestError as UnstableFrameStackRequestError,
 } from "../unstable-types";
-import type { PartialFrame, PartialFrameV2 } from "./types";
+import type { PartialFrame } from "./types";
 
 type FrameResultFailure = Exclude<GetFrameResult, { status: "success" }>;
 

packages/render/src/unstable-types.ts

@@ -1,12 +1,14 @@
 import type {
   FrameButtonLink,
   FrameButtonTx,
+  FrameV2,
   SupportedParsingSpecification,
   TransactionTargetResponse,
   TransactionTargetResponseSendTransaction,
   TransactionTargetResponseSignTypedDataV4,
 } from "frames.js";
 import type {
+  ParsedFrameV2,
   ParseFramesWithReportsResult,
   ParseResultWithFrameworkDetails,
 } from "frames.js/frame-parsers";
@@ -62,6 +64,40 @@ export type ResolveSignerFunction = (
 
 export type ResolveAddressFunction = () => Promise<`0x${string}` | null>;
 
+/**
+ * If partial frame rendering is enabled this is the shape of the frame
+ */
+export type PartialFrameV2 = Omit<ParsedFrameV2, "imageUrl" | "button"> & {
+  imageUrl: NonNullable<ParsedFrameV2["imageUrl"]>;
+  button: Omit<NonNullable<ParsedFrameV2["button"]>, "action" | "title"> & {
+    action: Omit<
+      NonNullable<NonNullable<ParsedFrameV2["button"]>["action"]>,
+      "url" | "title"
+    > & {
+      url: NonNullable<
+        NonNullable<NonNullable<ParsedFrameV2["button"]>["action"]>["url"]
+      >;
+    };
+    title: NonNullable<
+      NonNullable<NonNullable<ParsedFrameV2["button"]>["title"]>
+    >;
+  };
+};
+
+export type LaunchFrameButtonPressEvent =
+  | {
+      status: "complete";
+      frame: FrameV2;
+    }
+  | {
+      status: "partial";
+      frame: PartialFrameV2;
+    };
+
+export type LaunchFrameButtonPressFunction = (
+  event: LaunchFrameButtonPressEvent
+) => void;
+
 export type UseFrameOptions<
   TExtraDataPending = unknown,
   TExtraDataDone = unknown,
@@ -143,6 +179,12 @@ export type UseFrameOptions<
    * This function can be used to customize how the link button click is handled.
    */
   onLinkButtonClick?: OnLinkButtonClickFunction;
+  /**
+   * Called when the frame button is pressed.
+   *
+   * Only valid for frames v2.
+   */
+  onLaunchFrameButtonPress?: LaunchFrameButtonPressFunction;
 } & Partial<
   Pick<
     UseFetchFrameOptions,
@@ -278,6 +320,7 @@ export type UseFrameReturnValue<
   readonly inputText: string;
   setInputText: (s: string) => void;
   onButtonPress: ButtonPressFunction<SignerStateActionContext<any, any>>;
+  onLaunchFrameButtonPress: LaunchFrameButtonPressFunction;
   readonly homeframeUrl: string | null | undefined;
   /**
    * Resets the frame state to initial frame and resolves specification and signer again

packages/render/src/unstable-use-frame.tsx

@@ -407,6 +407,8 @@ export function useFrame_unstable<
     [frameStateRef, fetchFrameRef, onErrorRef, resolveAddressRef]
   );
 
+  const onLaunchFrameButtonPress = useCallback(() => {}, []);
+
   const onButtonPress = useCallback(
     async function onButtonPress(
       currentFrame: Frame,
@@ -532,6 +534,7 @@ export function useFrame_unstable<
       homeframeUrl,
       framesStack: stack,
       currentFrameStackItem: stack[0],
+      onLaunchFrameButtonPress,
     };
   }, [
     signerState,
@@ -544,5 +547,6 @@ export function useFrame_unstable<
     fetchFrame,
     homeframeUrl,
     stack,
+    onLaunchFrameButtonPress,
   ]);
 }