feat: add an interactive playground to the documentation site (#216)

Oh boy was this more of a pain than I expected. 

Creates an interactive playground similar to the typespec or typescript
ones, based on https://github.com/microsoft/monaco-editor

The actual code generation is off-loaded to a web worker, which actually
made the react side of things much simpler and easier to reason about,
and reduces blocking on the UI thread/main event loop.

Prettier is used instead of Biome due to difficulties getting the WASM
to load correctly in the browser / with nextjs. Unfortunately Prettier
hits a maximum recursion limit when formatting some of the larger files
(in firefox at least), so it would be good to revisit this and try and
get Biome working.

When loading the larger files, the performance of the editor gets a bit
shaky. I'm unsure if there is a way to offload more of the editor to web
workers to reduce strain on the UI thread.

**Demo Video**

https://github.com/user-attachments/assets/5b34f63e-9eaf-4e27-88e9-5a6a0bf5b9fe

packages/documentation/next.config.mjs

@@ -1,4 +1,5 @@
 import nextra from "nextra"
+import NodePolyfillPlugin from "node-polyfill-webpack-plugin"
 
 /** @type {import('next').NextConfig} */
 const nextConfig = {
@@ -8,6 +9,20 @@ const nextConfig = {
   images: {
     unoptimized: true,
   },
+  webpack: (config, {buildId, dev, isServer, defaultLoaders, webpack}) => {
+    config.experiments = {...config.experiments, syncWebAssembly: true}
+    config.plugins.push(new NodePolyfillPlugin())
+    config.module.rules.push({
+      test: /node:.+/i,
+      use: "null-loader",
+    })
+    config.module.rules.push({
+      test: /@biomejs\/wasm-nodejs/i,
+      use: "null-loader",
+    })
+
+    return config
+  },
   async redirects() {
     return [{source: "/", destination: "/overview/about", permanent: false}]
   },

packages/documentation/package.json

@@ -18,23 +18,34 @@
   },
   "scripts": {
     "clean": "rm -rf ./.next ./dist",
-    "dev": "next dev",
-    "build": "next build",
-    "lint": "next lint",
+    "dev": "yarn copy-sample-data && next dev",
+    "build": "yarn copy-sample-data && next build",
+    "lint": "yarn run -T lint",
+    "format": "yarn run -T format",
+    "copy-sample-data": "tsx ./scripts/copy-sample-data.ts",
     "publish:gh-pages": "yarn gh-pages -d ./dist -b gh-pages --cname openapi-code-generator.nahkies.co.nz --nojekyll"
   },
   "dependencies": {
+    "@hookform/resolvers": "^3.9.1",
+    "@monaco-editor/react": "^4.7.0-rc.0",
+    "@nahkies/openapi-code-generator": "*",
+    "monaco-editor": "^0.52.2",
+    "monaco-editor-auto-typings": "^0.4.6",
     "next": "15.1.3",
     "nextra": "^3.3.1",
     "nextra-theme-docs": "^3.3.1",
+    "node-polyfill-webpack-plugin": "^4.1.0",
     "react": "19.0.0",
-    "react-dom": "19.0.0"
+    "react-dom": "19.0.0",
+    "react-hook-form": "^7.54.2"
   },
   "devDependencies": {
     "@types/node": "^22.10.5",
     "@types/react": "^19.0.2",
     "@types/react-dom": "^19.0.2",
     "gh-pages": "^6.3.0",
+    "null-loader": "^4.0.1",
+    "tsx": "^4.19.2",
     "typescript": "^5.7.2"
   }
 }

packages/documentation/public/samples/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

packages/documentation/scripts/copy-sample-data.ts

@@ -0,0 +1,23 @@
+import {copyFile} from "node:fs/promises"
+import {dirname, resolve} from "node:path"
+import {fileURLToPath} from "node:url"
+import {sampleFilenames} from "../src/lib/playground/consts"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+for (const sample of sampleFilenames) {
+  const sourcePath = resolve(
+    __dirname,
+    `../../../integration-tests-definitions/${sample}`,
+  )
+  const destinationPath = resolve(__dirname, `../public/samples/${sample}`)
+
+  try {
+    await copyFile(sourcePath, destinationPath)
+    console.log(`Copied ${sample} to ${destinationPath}`)
+  } catch (err) {
+    console.error(`Failed to copy ${sample}:`, err)
+    throw err
+  }
+}

packages/documentation/src/lib/loading-spinner.module.css

@@ -0,0 +1,19 @@
+.loader {
+  width: 1rem;
+  height: 1rem;
+  border: 5px solid #363636;
+  border-bottom-color: transparent;
+  border-radius: 50%;
+  display: inline-block;
+  box-sizing: border-box;
+  animation: rotation 1s linear infinite;
+}
+
+@keyframes rotation {
+  0% {
+    transform: rotate(0deg);
+  }
+  100% {
+    transform: rotate(360deg);
+  }
+}

packages/documentation/src/lib/loading-spinner.tsx

@@ -0,0 +1,5 @@
+import styles from "./loading-spinner.module.css"
+
+export const LoadingSpinner = () => {
+  return <span className={styles.loader} />
+}

packages/documentation/src/lib/playground.module.css

@@ -0,0 +1,13 @@
+.editorContainer {
+  display: grid;
+  grid-template-columns: 1fr;
+  grid-template-rows: auto;
+
+  /*
+  TODO: rendering side-by-side results in weird stuff happening
+        when breakpoints change, stick with the vertical stack for now.
+  @media (min-width: 1536px) {
+    grid-template-columns: 1fr 1fr;
+  }
+   */
+}