From 6afa940b6568fe9af6a4976508aa1316851e0fdb Mon Sep 17 00:00:00 2001
From: ogp-weeloong <weeloong@open.gov.sg>
Date: Mon, 25 May 2026 16:17:11 +0800
Subject: [PATCH] feat: setup front end extensions for app

We want to allow apps to extend our front end (e.g. with tooltips)

This creates a new "app-extensions" system in front end to enable
this. The idea is to allow apps to provide react components that we
will render in appropriate parts of the frontend.

This kicks it off by extending the "check step" button

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/frontend/src/app-extensions/index.ts |  19 ++++
 packages/frontend/src/app-extensions/types.ts |  22 ++++
 .../CheckAgainButton.tsx                      |  22 ++--
 .../FlowStepTestController/index.tsx          | 107 +++++++++++-------
 4 files changed, 122 insertions(+), 48 deletions(-)
 create mode 100644 packages/frontend/src/app-extensions/index.ts
 create mode 100644 packages/frontend/src/app-extensions/types.ts

diff --git a/packages/frontend/src/app-extensions/index.ts b/packages/frontend/src/app-extensions/index.ts
new file mode 100644
index 0000000000..53942d2aba
--- /dev/null
+++ b/packages/frontend/src/app-extensions/index.ts
@@ -0,0 +1,19 @@
+import type { FrontEndAppExtension } from './types'
+
+// Nothing for now
+const APP_EXTENSIONS: Record<string, FrontEndAppExtension> = {}
+
+export function getExtension(
+  appKey?: string,
+  stepKey?: string,
+): FrontEndAppExtension | null {
+  if (!appKey || !stepKey) {
+    return null
+  }
+  return APP_EXTENSIONS[`${appKey}-${stepKey}`] ?? null
+}
+
+export type {
+  CheckStepButtonExtensionProps,
+  FrontEndAppExtension,
+} from './types'
diff --git a/packages/frontend/src/app-extensions/types.ts b/packages/frontend/src/app-extensions/types.ts
new file mode 100644
index 0000000000..d783c3e5ef
--- /dev/null
+++ b/packages/frontend/src/app-extensions/types.ts
@@ -0,0 +1,22 @@
+import type { IStep } from '@plumber/types'
+
+import type { ComponentType, ReactNode } from 'react'
+
+export interface CheckStepButtonExtensionProps {
+  step: IStep
+  /** The Check Step / Check Step Again button itself. */
+  children: ReactNode
+}
+
+export interface FrontEndAppExtension {
+  /**
+   * Wraps the Check Step / Check Step Again button.
+   *
+   * Mounted ONLY WHEN the button is enabled.
+   * TBD: Allow extending when button is disabled (for showing custom failure
+   *      tooltip etc)
+   **/
+  CheckStepButton?: ComponentType<CheckStepButtonExtensionProps>
+
+  // Room to grow: ResultPanelWrapper, SubstepWrapper, etc.
+}
diff --git a/packages/frontend/src/components/FlowStepTestController/CheckAgainButton.tsx b/packages/frontend/src/components/FlowStepTestController/CheckAgainButton.tsx
index 18e6f5d3d5..081b22715b 100644
--- a/packages/frontend/src/components/FlowStepTestController/CheckAgainButton.tsx
+++ b/packages/frontend/src/components/FlowStepTestController/CheckAgainButton.tsx
@@ -1,6 +1,6 @@
 import { IExecutionStepMetadata, IStep } from '@plumber/types'
 
-import { useCallback, useMemo } from 'react'
+import { forwardRef, useCallback, useMemo } from 'react'
 import { IconType } from 'react-icons'
 import { BiChevronDown } from 'react-icons/bi'
 import { PiRobot, PiUser } from 'react-icons/pi'
@@ -30,7 +30,10 @@ interface CheckAgainButtonProps {
   executionStepMetadata?: IExecutionStepMetadata
 }
 
-export function CheckAgainButton(props: CheckAgainButtonProps) {
+export const CheckAgainButton = forwardRef<
+  HTMLButtonElement,
+  CheckAgainButtonProps
+>((props, ref) => {
   const { isUnstyledInfobox, onClick, isLoading, isDisabled, step } = props
   const isFormSgTrigger =
     step.appKey === FORMSG_APP_KEY && step.key === FORMSG_TRIGGER_KEY
@@ -38,13 +41,14 @@ export function CheckAgainButton(props: CheckAgainButtonProps) {
     step.appKey === FORMSG_APP_KEY && step.key === MRF_ACTION_KEY
 
   if (isFormSgTrigger) {
-    return <FormSGCheckAgainButton {...props} />
+    return <FormSGCheckAgainButton ref={ref} {...props} />
   }
   if (isFormSgAction) {
-    return <FormSGCheckAgainButton {...props} />
+    return <FormSGCheckAgainButton ref={ref} {...props} />
   }
   return (
     <Button
+      ref={ref}
       variant={isUnstyledInfobox ? 'solid' : 'outline'}
       onClick={() => onClick()}
       isLoading={isLoading}
@@ -56,7 +60,7 @@ export function CheckAgainButton(props: CheckAgainButtonProps) {
       Check step again
     </Button>
   )
-}
+})
 
 /**
  * For UX reasons, we need to have a different button for FormSG.
@@ -104,7 +108,10 @@ function FormSGMenuItem({
   )
 }
 
-function FormSGCheckAgainButton(props: CheckAgainButtonProps) {
+const FormSGCheckAgainButton = forwardRef<
+  HTMLButtonElement,
+  CheckAgainButtonProps
+>((props, ref) => {
   const {
     isUnstyledInfobox: isTransparentInfobox,
     onClick,
@@ -155,6 +162,7 @@ function FormSGCheckAgainButton(props: CheckAgainButtonProps) {
       colorScheme={isTransparentInfobox ? 'primary' : 'black'}
     >
       <Button
+        ref={ref}
         onClick={onTestClick}
         isLoading={isLoading}
         gap={2}
@@ -190,4 +198,4 @@ function FormSGCheckAgainButton(props: CheckAgainButtonProps) {
       )}
     </ButtonGroup>
   )
-}
+})
diff --git a/packages/frontend/src/components/FlowStepTestController/index.tsx b/packages/frontend/src/components/FlowStepTestController/index.tsx
index ecacc36217..e872f8b603 100644
--- a/packages/frontend/src/components/FlowStepTestController/index.tsx
+++ b/packages/frontend/src/components/FlowStepTestController/index.tsx
@@ -1,6 +1,13 @@
 import { IBaseTrigger, IStep, ITriggerInstructions } from '@plumber/types'
 
-import { useContext, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  forwardRef,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
 import { useFormContext } from 'react-hook-form'
 import { BiChevronDown, BiChevronUp } from 'react-icons/bi'
 import {
@@ -20,6 +27,7 @@ import {
   Infobox,
 } from '@opengovsg/design-system-react'
 
+import { CheckStepButtonExtensionProps, getExtension } from '@/app-extensions'
 import { EditorContext } from '@/contexts/Editor'
 import { validateStepParams } from '@/helpers/validateStepParams'
 import { useStepMetadata } from '@/hooks/useStepMetadata'
@@ -63,25 +71,32 @@ type CheckStepTooltipProps = {
   children: React.ReactNode
 }
 
-const CheckStepTooltip = (props: CheckStepTooltipProps) => {
-  const { children, hasDeletedVars, isDisabled, isReadOnly } = props
-  return (
-    <Tooltip
-      label={
-        isReadOnly
-          ? 'Unpublish your pipe to check step'
-          : hasDeletedVars
-          ? 'Remove variables from deleted steps to check step'
-          : 'Complete required fields to check step'
-      }
-      aria-label="check step tooltip"
-      isDisabled={isDisabled}
-      hasArrow
-    >
-      {children}
-    </Tooltip>
-  )
-}
+const CheckStepTooltip = forwardRef<HTMLDivElement, CheckStepTooltipProps>(
+  (props, ref) => {
+    const { children, hasDeletedVars, isDisabled, isReadOnly } = props
+    return (
+      <Tooltip
+        ref={ref}
+        label={
+          isReadOnly
+            ? 'Unpublish your pipe to check step'
+            : hasDeletedVars
+            ? 'Remove variables from deleted steps to check step'
+            : 'Complete required fields to check step'
+        }
+        aria-label="check step tooltip"
+        isDisabled={isDisabled}
+        hasArrow
+      >
+        {children}
+      </Tooltip>
+    )
+  },
+)
+
+const NoOpCheckStepButtonExtension = ({
+  children,
+}: CheckStepButtonExtensionProps) => children
 
 export default function FlowStepTestController(
   props: FlowStepTestControllerProps,
@@ -248,6 +263,12 @@ export default function FlowStepTestController(
     return collapseDirection === 'up' ? <BiChevronUp /> : <BiChevronDown />
   }
 
+  const appExtension = getExtension(step.appKey, step.key)
+  const CheckStepButtonExtension =
+    shouldAllowCheckStep && appExtension?.CheckStepButton != null
+      ? appExtension.CheckStepButton
+      : NoOpCheckStepButtonExtension
+
   return (
     <>
       {isWebhookSubstep && (
@@ -337,14 +358,16 @@ export default function FlowStepTestController(
                       {!isDirty ? 'Saved' : 'Save without checking'}
                     </Button>
                   )}
-                  <CheckAgainButton
-                    isUnstyledInfobox={isStepUnchecked}
-                    onClick={handleSaveAndTest}
-                    isLoading={isTestExecuting}
-                    isDisabled={!isValid || readOnly}
-                    step={step}
-                    executionStepMetadata={currentTestExecutionStep?.metadata}
-                  />
+                  <CheckStepButtonExtension step={step}>
+                    <CheckAgainButton
+                      isUnstyledInfobox={isStepUnchecked}
+                      onClick={handleSaveAndTest}
+                      isLoading={isTestExecuting}
+                      isDisabled={!isValid || readOnly}
+                      step={step}
+                      executionStepMetadata={currentTestExecutionStep?.metadata}
+                    />
+                  </CheckStepButtonExtension>
                 </Flex>
               </Flex>
             </Infobox>
@@ -379,20 +402,22 @@ export default function FlowStepTestController(
                   {isDirty ? 'Save' : 'Saved'}
                 </Button>
               )}
-              <CheckStepTooltip
-                hasDeletedVars={hasDeletedVars}
-                isDisabled={shouldAllowCheckStep}
-                isReadOnly={readOnly}
-              >
-                <Button
-                  onClick={() => handleSaveAndTest()}
-                  data-test="flow-substep-continue-button"
-                  isDisabled={!shouldAllowCheckStep}
-                  isLoading={isTestExecuting}
+              <CheckStepButtonExtension step={step}>
+                <CheckStepTooltip
+                  hasDeletedVars={hasDeletedVars}
+                  isDisabled={shouldAllowCheckStep}
+                  isReadOnly={readOnly}
                 >
-                  Check step
-                </Button>
-              </CheckStepTooltip>
+                  <Button
+                    onClick={() => handleSaveAndTest()}
+                    data-test="flow-substep-continue-button"
+                    isDisabled={!shouldAllowCheckStep}
+                    isLoading={isTestExecuting}
+                  >
+                    Check step
+                  </Button>
+                </CheckStepTooltip>
+              </CheckStepButtonExtension>
             </HStack>
           </VStack>
         )}