Add bidirectional form communication API for dashboard apps

.changeset/yellow-bees-enjoy.md

@@ -0,0 +1,5 @@
+---
+"@saleor/app-sdk": patch
+---
+
+Added new API for communication around forms (TODO)

.gitignore

@@ -117,3 +117,5 @@ dist
 
 .idea/
 .vscode/
+
+coverage.json

README.md

@@ -28,7 +28,7 @@ Supports Saleor version 3.20+
   - Create a legacy release branch (e.g. `v1.x` branch)
   - Mark changeset to `main` with `major` change, which will start counting next `main` releases as `2.x.x`
   - Do not merge release PR until it's ready to be merged
- 
+
 ### Deploying test snapshots
 
 PRs can be pushed to NPM by adding label to PR `release dev tag`. Workflow will run and print version that has been released.

src/APL/redis/redis-apl.test.ts

@@ -84,7 +84,7 @@ describe("RedisAPL", () => {
       await defaultApl.get(mockAuthData.saleorApiUrl);
       expect(mockRedisClient.hGet).toHaveBeenCalledWith(
         "saleor_app_auth",
-        mockAuthData.saleorApiUrl
+        mockAuthData.saleorApiUrl,
       );
     });
   });
@@ -117,7 +117,7 @@ describe("RedisAPL", () => {
       expect(mockHSet).toHaveBeenCalledWith(
         mockHashKey,
         mockAuthData.saleorApiUrl,
-        JSON.stringify(mockAuthData)
+        JSON.stringify(mockAuthData),
       );
     });
 

src/APL/redis/redis-apl.ts

@@ -112,7 +112,7 @@ export class RedisAPL implements APL {
 
           throw e;
         }
-      }
+      },
     );
   }
 
@@ -136,7 +136,7 @@ export class RedisAPL implements APL {
           await this.client.hSet(
             this.hashCollectionKey,
             authData.saleorApiUrl,
-            JSON.stringify(authData)
+            JSON.stringify(authData),
           );
 
           this.debug("Successfully set auth data in Redis");
@@ -155,7 +155,7 @@ export class RedisAPL implements APL {
 
           throw e;
         }
-      }
+      },
     );
   }
 
@@ -193,7 +193,7 @@ export class RedisAPL implements APL {
 
           throw e;
         }
-      }
+      },
     );
   }
 
@@ -232,7 +232,7 @@ export class RedisAPL implements APL {
 
           throw e;
         }
-      }
+      },
     );
   }
 

src/APL/saleor-cloud/paginator.ts

@@ -12,7 +12,7 @@ export class Paginator<ResultType> {
   constructor(
     private readonly url: string,
     private readonly fetchOptions: RequestInit,
-    private readonly fetchFn = fetch
+    private readonly fetchFn = fetch,
   ) {}
 
   public async fetchAll() {

src/APL/saleor-cloud/saleor-cloud-apl-errors.ts

@@ -1,5 +1,8 @@
 export class SaleorCloudAplError extends Error {
-  constructor(public code: string, message: string) {
+  constructor(
+    public code: string,
+    message: string,
+  ) {
     super(message);
     this.name = "SaleorCloudAplError";
   }

src/APL/vercel-kv/vercel-kv-apl.ts

@@ -76,7 +76,7 @@ export class VercelKvApl implements APL {
 
           throw e;
         }
-      }
+      },
     );
   }
 
@@ -118,7 +118,7 @@ export class VercelKvApl implements APL {
 
           throw e;
         }
-      }
+      },
     );
   }
 
@@ -157,7 +157,7 @@ export class VercelKvApl implements APL {
 
           throw e;
         }
-      }
+      },
     );
   }
 

src/app-bridge/actions.test.ts

@@ -39,6 +39,42 @@ describe("actions.ts", () => {
     });
   });
 
+  describe("actions.FormPayloadUpdate", () => {
+    it("Constructs action with \"formPayloadUpdate\" type, random id and payload for product translation", () => {
+      const payload = {
+        form: "product-translate" as const,
+        fields: {
+          productName: { value: "Updated Product Name" },
+          productDescription: { value: "Updated Description" },
+          seoName: { value: "Updated SEO Name" },
+        },
+      };
+
+      const action = actions.FormPayloadUpdate(payload);
+
+      expect(action.type).toBe("formPayloadUpdate");
+      expect(action.payload.actionId).toEqual(expect.any(String));
+      expect(action.payload).toEqual(expect.objectContaining(payload));
+    });
+
+    it("Constructs action with field value results", () => {
+      const payload = {
+        form: "product-translate" as const,
+        fields: {
+          productName: { value: "New Name" },
+          productDescription: { value: "New Description" },
+          seoName: { value: "New SEO" },
+          seoDescription: { value: "New SEO Description" },
+        },
+      };
+
+      const action = actions.FormPayloadUpdate(payload);
+
+      expect(action.payload.fields.productName).toEqual({ value: "New Name" });
+      expect(action.payload.fields.productDescription).toEqual({ value: "New Description" });
+    });
+  });
+
   it("Throws custom error if crypto is not available", () => {
     vi.stubGlobal("crypto", {
       ...globalThis.crypto,

src/app-bridge/actions.ts

@@ -1,3 +1,8 @@
+import {
+  AllFormPayloadUpdatePayloads,
+  formPayloadUpdateActionName,
+} from "@/app-bridge/form-payload";
+
 import { AppPermission } from "../types";
 import { Values } from "./helpers";
 
@@ -25,6 +30,12 @@ export const ActionType = {
    * Available from 3.15
    */
   requestPermission: "requestPermissions",
+  /**
+   * Apply form fields in active context.
+   *
+   * EXPERIMENTAL
+   */
+  formPayloadUpdate: formPayloadUpdateActionName,
 } as const;
 
 export type ActionType = Values<typeof ActionType>;
@@ -127,6 +138,11 @@ export type RequestPermissions = ActionWithId<
   }
 >;
 
+export type FormPayloadUpdate = ActionWithId<
+  typeof formPayloadUpdateActionName,
+  AllFormPayloadUpdatePayloads
+>;
+
 function createRequestPermissionsAction(
   permissions: AppPermission[],
   redirectPath: string,
@@ -140,11 +156,20 @@ function createRequestPermissionsAction(
   });
 }
 
+function createFormPayloadUpdateAction(payload: AllFormPayloadUpdatePayloads): FormPayloadUpdate {
+  return withActionId({
+    type: formPayloadUpdateActionName,
+    // @ts-ignore - TODO: For some reason TS is failing here, but this is internal implementation so it doesn't change the public API
+    payload,
+  });
+}
+
 export type Actions =
   | RedirectAction
   | NotificationAction
   | UpdateRouting
   | NotifyReady
+  | FormPayloadUpdate
   | RequestPermissions;
 
 export const actions = {
@@ -153,4 +178,5 @@ export const actions = {
   UpdateRouting: createUpdateRoutingAction,
   NotifyReady: createNotifyReadyAction,
   RequestPermissions: createRequestPermissionsAction,
+  FormPayloadUpdate: createFormPayloadUpdateAction,
 };

src/app-bridge/app-bridge-provider.tsx

@@ -42,7 +42,7 @@ export function AppBridgeProvider({ appBridgeInstance, ...props }: React.PropsWi
       appBridge,
       mounted: true,
     }),
-    [appBridge]
+    [appBridge],
   );
 
   return <AppContext.Provider value={contextValue} {...props} />;
@@ -51,7 +51,7 @@ export function AppBridgeProvider({ appBridgeInstance, ...props }: React.PropsWi
 export const useAppBridge = () => {
   const { appBridge, mounted } = useContext(AppContext);
   const [appBridgeState, setAppBridgeState] = useState<AppBridgeState | null>(() =>
-    appBridge ? appBridge.getState() : null
+    appBridge ? appBridge.getState() : null,
   );
 
   if (typeof window !== "undefined" && !mounted) {

src/app-bridge/app-bridge-state.ts

@@ -1,3 +1,5 @@
+import { AllFormPayloads } from "@/app-bridge/form-payload";
+
 import { LocaleCode } from "../locales";
 import { AppPermission, Permission } from "../types";
 import { ThemeType } from "./events";
@@ -24,6 +26,7 @@ export type AppBridgeState = {
     email: string;
   };
   appPermissions?: AppPermission[];
+  formContext?: AllFormPayloads;
 };
 
 type Options = {