From 7f40af00cea99afed8e8ec33301bce811607f076 Mon Sep 17 00:00:00 2001
From: Jack Zhao <bugzpodder@hotmail.com>
Date: Sat, 4 Nov 2023 15:31:30 +0000
Subject: [PATCH] react example

---
 docs/astro.config.mjs                         |  3 +-
 docs/package.json                             |  2 +-
 docs/src/components/PySandboxExample.astro    |  8 ++--
 docs/src/content/docs/guides/comparison.md    | 10 +++--
 .../docs/guides/{examples.mdx => demo.mdx}    |  4 +-
 docs/src/content/docs/guides/installation.md  |  2 +-
 docs/src/content/docs/guides/introduction.md  |  4 +-
 docs/src/content/docs/guides/react.md         | 38 +++++++++++++++++++
 docs/src/content/docs/index.mdx               |  8 ++--
 docs/src/content/docs/references/index.md     |  2 +-
 10 files changed, 62 insertions(+), 19 deletions(-)
 rename docs/src/content/docs/guides/{examples.mdx => demo.mdx} (95%)
 create mode 100644 docs/src/content/docs/guides/react.md

diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 1665951..d4dff68 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -26,8 +26,9 @@ export default defineConfig({
             // Each item here is one entry in the navigation menu.
             { label: "Introduction", link: "guides/introduction" },
             { label: "Comparison", link: "guides/comparison" },
-            { label: "Examples", link: "guides/examples" },
+            { label: "Demo", link: "guides/demo" },
             { label: "Installation", link: "guides/installation" },
+            { label: "React Integration", link: "guides/react" },
           ],
         },
         { label: "Documentation", autogenerate: { directory: "references" } },
diff --git a/docs/package.json b/docs/package.json
index 2ccc46a..d9c8533 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -11,7 +11,7 @@
     "build": "astro build",
     "preview": "astro preview",
     "astro": "astro",
-    "format": "prettier -w src src/**/*.astro *.mjs *.js *.json *.css"
+    "format": "prettier -w src src/**/*.astro *.mjs *.js *.json"
   },
   "dependencies": {
     "@astrojs/starlight": "^0.10.0",
diff --git a/docs/src/components/PySandboxExample.astro b/docs/src/components/PySandboxExample.astro
index 6319cb7..6b960c8 100644
--- a/docs/src/components/PySandboxExample.astro
+++ b/docs/src/components/PySandboxExample.astro
@@ -20,14 +20,14 @@ const { code, target, worker, restricted } = Astro.props;
   }
 </style>
 
-<div style="border: 1px solid; padding: 4px; margin-bottom: 4px;">
-  Output:<div id={target} style="min-height: 500px"></div>
-</div>
-
 <div id="code-editor" style="margin-bottom: 1.5rem; height: 300px"></div>
 <button class="format">Format Code</button>
 <button class="run" style="margin-left: 4px">Run code</button>
 
+<div style="border: 1px solid; padding: 4px; margin-top: 4px;">
+  Output:<div id={target} style="min-height: 500px"></div>
+</div>
+
 <pysandbox-example
   data-code={code}
   data-target={target}
diff --git a/docs/src/content/docs/guides/comparison.md b/docs/src/content/docs/guides/comparison.md
index 01b79fe..0c0f8fa 100644
--- a/docs/src/content/docs/guides/comparison.md
+++ b/docs/src/content/docs/guides/comparison.md
@@ -5,10 +5,14 @@ description: A comparison of PySandbox and other libraries.
 
 ## Pyodide
 
-PySandbox uses [Pyodide](https://github.com/pyodide/pyodide) under the hood. If you are running python code on the main thread, it's fairly simple to bootstrap Pyodide directly in your code. On the other hand, PySandbox will provide additional utilities like `display` for showing pyplots and managing other [IPython](https://ipython.readthedocs.io/en/stable/config/integrating.html) outputs.
+PySandbox uses [Pyodide](https://github.com/pyodide/pyodide) under the hood. If you are running python code on the main thread, it's fairly simple to bootstrap Pyodide directly in your code. PySandbox will provide additional utilities like `display` for showing pyplots and managing other [IPython](https://ipython.readthedocs.io/en/stable/config/integrating.html) outputs.
 
-Pyodide does not setup web workers out of the box. If you site is [crossOriginIsolated](https://web.dev/coop-coep/), PySandbox can be easily configured to execute python code in a web worker.
+Pyodide does not setup web workers out of the box. If you site is [crossOriginIsolated](https://web.dev/coop-coep), PySandbox can be easily configured to execute python code in a web worker.
 
 ## PyScript
 
-[PyScript](https://pyscript.net/) is great for configuring a single html page to run python code as well as providing acess to DOM through its `pyweb` API. `PyScript` adopts a RPC pattern by letting Python code manipulate the DOM and react to events, while `PySandbox` is intended to be a traditional REST backend. If you are using a JS web-framework (e.g. a React-based framework) to build your web application, you may find `PySandbox` easier to use with its pure JS invocation without needing to rely on `<script type="py">` and `<py-script>` tags.
+[PyScript](https://pyscript.net) is great for configuring a single html page to run Python code as well as providing acess to DOM through its `pyweb` API. Python code in `PyScript` is defined in custom script tags such as `<script type="py"></script>`. If you are using a JS web-framework (e.g. a React-based framework) to build your web application, you may find `PySandbox` easier to use with its pure JS invocation without needing to rely on `<script type="py">` and `<py-script>` tags.
+
+## react-py
+
+[react-py](elilambnz.github.io/react-py) is a React package that provides out-of-box support for many Pyodide functionalities. `PySandbox` package is not React specific and offers more flexibility in its APIs. This [guide](/pysandbox/guides/react) covers how to use `PySandbox` in React.
diff --git a/docs/src/content/docs/guides/examples.mdx b/docs/src/content/docs/guides/demo.mdx
similarity index 95%
rename from docs/src/content/docs/guides/examples.mdx
rename to docs/src/content/docs/guides/demo.mdx
index 45f0078..2d44502 100644
--- a/docs/src/content/docs/guides/examples.mdx
+++ b/docs/src/content/docs/guides/demo.mdx
@@ -1,6 +1,6 @@
 ---
-title: Examples
-description: Examples of PySandbox.
+title: Demo
+description: PySandbox Demo.
 ---
 
 Here is a Python REPL powered by PySandbox and [Xterm.js](https://xtermjs.org/).
diff --git a/docs/src/content/docs/guides/installation.md b/docs/src/content/docs/guides/installation.md
index 7e4d7a6..1eac5ea 100644
--- a/docs/src/content/docs/guides/installation.md
+++ b/docs/src/content/docs/guides/installation.md
@@ -9,7 +9,7 @@ Usage in html:
 
 ```html
 <script type="module">
-  import { PyMainThreadSandbox } from "https://esm.sh/pysandbox@latest/";
+  import { PyMainThreadSandbox } from "https://esm.sh/pysandbox@latest";
   const sandbox = new PyMainThreadSandbox();
   await sandbox.init();
   await sandbox.exec("display('Hello', target=current_target())", "output");
diff --git a/docs/src/content/docs/guides/introduction.md b/docs/src/content/docs/guides/introduction.md
index 0fa46fc..a5082a0 100644
--- a/docs/src/content/docs/guides/introduction.md
+++ b/docs/src/content/docs/guides/introduction.md
@@ -9,9 +9,9 @@ PySandbox is a library that helps developers create client-side Python-powered w
 
 The main features of PySandbox are:
 
-- Exports simple JS classes that can be used in any JS framework or html page.
+- Exports JS classes that can be used in any JS framework or html page.
 - Web Worker ready. If your site is cross origin isolated, Web Workers can be used to execute python code.
 - Restricted mode. Enabling this mode will disallow python scripts access to js.document.
-- Custom modules support. You can define your own modules that are accessible in the codeblock.
+- Custom modules support. You can define your own modules that are accessible in the code.
 - Input/Output support. You can easily pass data in and out of the python code blocks and display images and/or adding 3rd party JS integration.
 - Helper methods for formatting code, find imports and installing modules in Pyodide.
diff --git a/docs/src/content/docs/guides/react.md b/docs/src/content/docs/guides/react.md
new file mode 100644
index 0000000..6a8bb4a
--- /dev/null
+++ b/docs/src/content/docs/guides/react.md
@@ -0,0 +1,38 @@
+---
+title: React Integration
+description: Use PySandbox in React.
+---
+
+The easiest way to use `PySandbox` in a React application is by using the `useEffect` hook to execute the Python code.
+
+```js
+import { useEffect, useId, useRef } from "react";
+import { PyMainThreadSandbox } from "pysandbox";
+
+function usePython() {
+  const ref = useRef();
+  return {
+    runPython: async (code, id) => {
+      if (!ref.current) {
+        ref.current = new PyMainThreadSandbox();
+      }
+      const sandbox = ref.current;
+      await sandbox.init();
+      if (id) {
+        document.getElementById(id).replaceChildren();
+      }
+      await sandbox.exec(code, id);
+    },
+  };
+}
+
+function CodeBlock({ code }) {
+  const id = useId();
+  const { runPython } = usePython();
+  useEffect(() => {
+    runPython(code, id);
+  }, [code]);
+
+  return <div id={id} />;
+}
+```
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
index 85bd02e..dece619 100644
--- a/docs/src/content/docs/index.mdx
+++ b/docs/src/content/docs/index.mdx
@@ -1,6 +1,6 @@
 ---
 title: Welcome to PySandbox
-description: Get started incorporating python code to your app.
+description: Get started incorporating python code in your web application.
 template: splash
 hero:
   tagline: Run Python in Your Web Application
@@ -8,7 +8,7 @@ hero:
     file: ../../assets/pysandbox.webp
   actions:
     - text: Try it out
-      link: /pysandbox/examples/mainthread/example3_seaborn
+      link: /pysandbox/guides/demo
       icon: right-arrow
       variant: primary
     - text: View on GitHub
@@ -25,9 +25,9 @@ import { LinkCard, CardGrid } from "@astrojs/starlight/components";
     href="/pysandbox/guides/introduction"
   />
   <LinkCard
-    title="Examples"
+    title="Demo"
     description="Adding Python visualizations backed by IPython and matplotlib into your application."
-    href="/pysandbox/guides/examples"
+    href="/pysandbox/guides/demo"
   />
   <LinkCard
     title="Install"
diff --git a/docs/src/content/docs/references/index.md b/docs/src/content/docs/references/index.md
index 2d943d7..b6b6932 100644
--- a/docs/src/content/docs/references/index.md
+++ b/docs/src/content/docs/references/index.md
@@ -7,7 +7,7 @@ The `pysandbox` library exports two classes: `PyMainThreadSandbox` and `PyWorker
 
 `PyMainThreadSandbox` will execute python code on the main thread while `PyWorkerSandbox` will execute python code in a web worker if [crossOriginIsolated](https://web.dev/coop-coep/).
 
-Both classes shares an identical interface.
+Both classes shares an identical interface and can be instantiated by passing in [PySandboxOptions](/pysandbox/references/options).
 
 ```js
 interface ISandbox {