feat: display sandbox in the docs for quick visualization

docs/astro.config.mjs

@@ -1,16 +1,54 @@
 // @ts-check
+import react from '@astrojs/react'
 import starlight from '@astrojs/starlight'
+import tailwind from '@astrojs/tailwind'
 import { defineConfig } from 'astro/config'
 
 import { mermaid } from './src/plugins/mermaid'
 
 export default defineConfig({
+  vite: {
+    resolve: {
+      /**
+       * @uiw/* packages are not compatible with ESM, as they do not import with `.js` extension.
+       * We're using source in TypeScript instead.
+       */
+      alias: {
+        '@uiw/react-codemirror': '@uiw/react-codemirror/src/index.tsx',
+        '@uiw/codemirror-extensions-basic-setup':
+          '@uiw/codemirror-extensions-basic-setup/src/index.ts',
+        '@uiw/codemirror-theme-abyss': '@uiw/codemirror-theme-abyss/src/index.ts',
+        '@uiw/codemirror-themes': '@uiw/codemirror-themes/src/index.tsx',
+      },
+      conditions: ['bun'],
+    },
+    optimizeDeps: {
+      /**
+       * We need to tell Vite to process @uiw/* and related packages, so we transpile them
+       * properly.
+       */
+      include: [
+        '@uiw/codemirror-extensions-basic-setup',
+        '@codemirror/state',
+        '@codemirror/view',
+        '@codemirror/language',
+        '@uiw/codemirror-theme-abyss',
+        '@uiw/codemirror-themes',
+        '@codemirror/lang-javascript',
+      ],
+    },
+  },
   integrations: [
+    react(),
+    tailwind({
+      applyBaseStyles: false,
+    }),
     starlight({
       title: 'Flows AI',
       social: {
         github: 'https://github.com/callstackincubator/flows-ai',
       },
+      customCss: ['./src/styles/base.css'],
       sidebar: [
         {
           label: 'Introduction',
@@ -30,6 +68,10 @@ export default defineConfig({
           label: 'Guides',
           autogenerate: { directory: 'guides' },
         },
+        {
+          label: 'Sandbox',
+          slug: 'sandbox',
+        },
       ],
     }),
   ],

docs/package.json

@@ -2,11 +2,23 @@
   "name": "docs-new",
   "version": "0.0.1",
   "dependencies": {
+    "@astrojs/react": "^4.1.6",
     "@astrojs/starlight": "^0.31.1",
+    "@astrojs/starlight-tailwind": "^3.0.0",
+    "@astrojs/tailwind": "^5.1.5",
+    "@codemirror/lang-javascript": "^6.2.2",
     "@expressive-code/plugin-collapsible-sections": "^0.40.1",
+    "@flows-ai/ui": "workspace:*",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@uiw/codemirror-theme-abyss": "^4.23.7",
+    "@uiw/react-codemirror": "^4.23.7",
     "astro": "^5.1.5",
     "mermaid": "^11.4.1",
-    "sharp": "^0.32.5"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "sharp": "^0.32.5",
+    "tailwindcss": "^3.4.17"
   },
   "private": true,
   "scripts": {

docs/src/components/Sandbox.tsx

@@ -0,0 +1,62 @@
+import { javascript } from '@codemirror/lang-javascript'
+import { Flow } from '@flows-ai/ui'
+import { abyss } from '@uiw/codemirror-theme-abyss'
+import ReactCodeMirror from '@uiw/react-codemirror'
+import s from 'dedent'
+import { useEffect, useState } from 'react'
+
+const defaultCode = s`
+  import { parallel } from 'https://esm.sh/flows-ai/flows';
+
+  export default parallel([
+    {
+      agent: 'githubAgent',
+      input: 'Get me the latest commit message from the main branch of the flows-ai repo',
+    }
+  ])
+`
+
+export function Sandbox() {
+  const [code, setCode] = useState(defaultCode)
+  const [result, setResult] = useState<any>(null)
+
+  const evaluateCode = async () => {
+    try {
+      const blob = new Blob([code], { type: 'text/javascript' })
+      const url = URL.createObjectURL(blob)
+
+      const module = await import(/* @vite-ignore */ url)
+      setResult(module.default)
+
+      URL.revokeObjectURL(url)
+    } catch (error) {
+      console.error(error)
+      setResult(null)
+    }
+  }
+
+  useEffect(() => {
+    evaluateCode()
+  }, [])
+
+  return (
+    <div className="grid grid-cols-2 gap-4 not-content">
+      <ReactCodeMirror
+        className="w-full"
+        value={code}
+        onChange={(value) => setCode(value)}
+        onBlur={evaluateCode}
+        basicSetup={{
+          syntaxHighlighting: true,
+        }}
+        extensions={[javascript({ jsx: true, typescript: true })]}
+        theme={abyss}
+      />
+      {result && (
+        <div className="w-full h-[600px]">
+          <Flow flow={result} />
+        </div>
+      )}
+    </div>
+  )
+}

docs/src/content/docs/sandbox.mdx

@@ -0,0 +1,10 @@
+---
+title: Sandbox
+tableOfContents: false
+pagination: false
+---
+import '@/styles/full-screen.css'
+import { Sandbox } from '@/components/Sandbox'
+
+<Sandbox client:load />
+

docs/src/styles/base.css

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

docs/src/styles/full-screen.css

@@ -0,0 +1,3 @@
+:root {
+  --sl-content-width: 100%;
+}

docs/tailwind.config.mjs

@@ -0,0 +1,16 @@
+import starlightPlugin from '@astrojs/starlight-tailwind'
+import colors from 'tailwindcss/colors'
+
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
+  plugins: [starlightPlugin()],
+  theme: {
+    extend: {
+      colors: {
+        accent: colors.purple,
+        gray: colors.zinc,
+      },
+    },
+  },
+}

docs/tsconfig.json

@@ -1,11 +1,10 @@
 {
-  "extends": "astro/tsconfigs/strict",
-  "include": [".astro/types.d.ts", "**/*"],
-  "exclude": ["dist"],
+  "extends": "../tsconfig.json",
   "compilerOptions": {
     "baseUrl": ".",
     "paths": {
-      "@/*": ["./src/*"]
+      "@/*": ["./src/*"],
     }
   }
 }
+

packages/builder/package.json → packages/ui/package.json

@@ -1,17 +1,25 @@
 {
-  "name": "@flows-ai/builder",
-  "private": true,
+  "name": "@flows-ai/ui",
   "version": "0.2.1",
   "type": "module",
+  "exports": {
+    "bun": "./src/index.ts",
+    "types": {
+      "import": "./dist/index.d.ts",
+      "require": "./dist/index.d.cts"
+    },
+    "require": "./dist/index.cjs",
+    "import": "./dist/index.js"
+  },
   "scripts": {
-    "dev": "vite",
-    "build": "tsc -b && vite build",
-    "lint": "eslint .",
-    "preview": "vite preview"
+    "prepare": "bun run build",
+    "build": "tsup-node"
   },
   "dependencies": {
     "@dagrejs/dagre": "^1.1.4",
-    "@xyflow/react": "^12.4.1",
+    "@xyflow/react": "^12.4.1"
+  },
+  "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },