feat(WebSandbox): add custom event to allow sending notifications from sandbox to Python

Author: Col0ring

.changeset/violet-candles-switch.md

@@ -0,0 +1,6 @@
+---
+'@modelscope-studio/pro': patch
+'modelscope_studio': patch
+---
+
+feat: add `custom` event to allow sending notifications from sandbox to Python

backend/modelscope_studio/components/pro/web_sandbox/__init__.py

@@ -26,6 +26,9 @@ class ModelScopeProWebSandbox(ModelScopeLayoutComponent):
         EventListener("render_error",
                       callback=lambda block: block._internal.update(
                           bind_renderError_event=True)),
+        EventListener("custom",
+                      callback=lambda block: block._internal.update(
+                          bind_custom_event=True)),
     ]
 
     # supported slots

docs/components/pro/web_sandbox/README-zh_CN.md

@@ -23,6 +23,10 @@
 
 <demo name="html"></demo>
 
+### 自定义 Sandbox 事件
+
+<demo name="custom_sandbox_event"></demo>
+
 ### 处理错误
 
 <demo name="error_handling"></demo>
@@ -43,11 +47,12 @@
 
 ### 事件
 
-| 事件                                      | 描述                        |
-| ----------------------------------------- | --------------------------- |
-| `pro.WebSandbox.compile_success(fn, ···)` | 当 Sandbox 编译成功时触发。 |
-| `pro.WebSandbox.compile_error(fn, ···)`   | 当 Sandbox 编译失败时触发。 |
-| `pro.WebSandbox.render_error(fn, ···)`    | 当 Sandbox 渲染抛错时触发。 |
+| 事件                                      | 描述                                                                                        |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `pro.WebSandbox.compile_success(fn, ···)` | 当 Sandbox 编译成功时触发。                                                                 |
+| `pro.WebSandbox.compile_error(fn, ···)`   | 当 Sandbox 编译失败时触发。                                                                 |
+| `pro.WebSandbox.render_error(fn, ···)`    | 当 Sandbox 渲染抛错时触发。                                                                 |
+| `pro.WebSandbox.custom(fn, ···)`          | 在 Sandbox 内触发的自定义事件，在 Sandbox 内通过 JavaScript 调用 `window.dispatch` 时触发。 |
 
 ### 插槽
 

docs/components/pro/web_sandbox/README.md

@@ -23,6 +23,10 @@ When `template` is set to `react`, the following dependencies will be automatica
 
 <demo name="html"></demo>
 
+### Custom Sandbox Event
+
+<demo name="custom_sandbox_event"></demo>
+
 ### Error Handling
 
 <demo name="error_handling"></demo>
@@ -43,11 +47,13 @@ When `template` is set to `react`, the following dependencies will be automatica
 
 ### Events
 
-| Event                                     | Description                                       |
-| ----------------------------------------- | ------------------------------------------------- |
-| `pro.WebSandbox.compile_success(fn, ···)` | Triggered when Sandbox compilation succeeds.      |
-| `pro.WebSandbox.compile_error(fn, ···)`   | Triggered when Sandbox compilation fails.         |
-| `pro.WebSandbox.render_error(fn, ···)`    | Triggered when Sandbox rendering throws an error. |
+| Event                                     | Description                                                                                                                |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `pro.WebSandbox.compile_success(fn, ···)` | Triggered when Sandbox compilation succeeds.                                                                               |
+| `pro.WebSandbox.compile_error(fn, ···)`   | Triggered when Sandbox compilation fails.                                                                                  |
+| `pro.WebSandbox.render_error(fn, ···)`    | Triggered when Sandbox rendering throws an error.                                                                          |
+| `pro.WebSandbox.render_error(fn, ···)`    | Triggered when Sandbox rendering throws an error.                                                                          |
+| `pro.WebSandbox.custom(fn, ···)`          | Custom events triggered within the Sandbox are invoked via JavaScript when `window.dispatch` is called within the Sandbox. |
 
 ### Slots
 

docs/components/pro/web_sandbox/demos/custom_sandbox_event.py

@@ -0,0 +1,26 @@
+import gradio as gr
+import modelscope_studio.components.antd as antd
+import modelscope_studio.components.base as ms
+import modelscope_studio.components.pro as pro
+
+
+def on_custom(e: gr.EventData):
+    print(e._data)
+
+
+with gr.Blocks() as demo, ms.Application(), antd.ConfigProvider():
+    sandbox = pro.WebSandbox(value={
+        "index.tsx":
+        """
+export default function App() {
+  return <button onClick={() => {
+    window.dispatch({ type: 'custom', payload: { value: 'test' } })
+  } }>Click to emit custom event to Python</button>;
+}
+"""
+    },
+                             template="react")
+    sandbox.custom(fn=on_custom)
+
+if __name__ == "__main__":
+    demo.queue().launch()

frontend/pro/web-sandbox/web-sandbox.tsx

@@ -28,6 +28,7 @@ export interface WebSandboxProps {
   onCompileError?: (message: string) => void;
   onCompileSuccess?: () => void;
   onRenderError?: (message: string) => void;
+  onCustom?: (...args: any[]) => void;
   height?: string | number;
   themeMode: string;
   setSlotParams: SetSlotParams;
@@ -53,6 +54,7 @@ export const WebSandbox = sveltify<WebSandboxProps, ['compileErrorRender']>(
     onRenderError,
     onCompileSuccess,
     compileErrorRender,
+    onCustom,
   }) => {
     const iframeRef = React.useRef<HTMLIFrameElement>(null);
     const divRef = React.useRef<HTMLDivElement>(null);
@@ -75,6 +77,7 @@ export const WebSandbox = sveltify<WebSandboxProps, ['compileErrorRender']>(
     const onCompileErrorMemoized = useMemoizedFn(onCompileError);
     const onRenderErrorMemoized = useMemoizedFn(onRenderError);
     const onCompileSuccessMemoized = useMemoizedFn(onCompileSuccess);
+    const onCustomMemoized = useMemoizedFn(onCustom);
 
     // Build import map (only includes third-party dependencies)
     const resolvedImportMap = useMemo(() => {
@@ -248,6 +251,8 @@ export const WebSandbox = sveltify<WebSandboxProps, ['compileErrorRender']>(
           try {
             // Inject theme
             (iframeRef.current.contentWindow as any).gradio_theme = themeMode;
+            (iframeRef.current.contentWindow as any).dispatch =
+              onCustomMemoized;
           } catch {
             //
           }
@@ -288,6 +293,7 @@ export const WebSandbox = sveltify<WebSandboxProps, ['compileErrorRender']>(
       iframeUrl,
       notificationApi,
       onCompileSuccessMemoized,
+      onCustomMemoized,
       onRenderErrorMemoized,
       showRenderError,
       themeMode,