improve playground ux

Author: pgherveou

playground/src/app/page.tsx

@@ -1,6 +1,12 @@
 "use client";
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
 import {
   subscribeConnectionStatus,
   type ConnectionStatus,
@@ -24,6 +30,11 @@ import packageJson from "../../package.json";
 
 const VERSION_LABEL = `v${packageJson.version}`;
 
+// Run the scroll-restore synchronously after the index re-mounts so the
+// previously-open row is centered before paint (no flash of scroll-top).
+const useIsoLayoutEffect =
+  typeof window !== "undefined" ? useLayoutEffect : useEffect;
+
 // Stable empty map so a view that does not own the current results re-renders
 // with an empty object rather than a fresh `{}` each render.
 const EMPTY_RESULTS: Record<string, TestEntry> = {};
@@ -136,6 +147,8 @@ function urlForSelection(selection: Selection): string {
 export default function PlaygroundPage() {
   const [status, setStatus] = useState<ConnectionStatus | null>(null);
   const [selection, setSelection] = useState<Selection>(null);
+  // The last method viewed, kept highlighted in the index after "← INDEX".
+  const [lastViewed, setLastViewed] = useState<Selection>(null);
   const [paletteOpen, setPaletteOpen] = useState(false);
   const [testResults, setTestResults] = useState<Record<string, TestEntry>>({});
   const [isTestRunning, setIsTestRunning] = useState(false);
@@ -145,6 +158,9 @@ export default function PlaygroundPage() {
     "autotest" | "diagnosis" | null
   >(null);
   const abortRef = useRef<AbortController | null>(null);
+  // The method open when "← INDEX" was clicked, so the index can re-center on
+  // it instead of jumping to the top.
+  const pendingScrollRef = useRef<Selection>(null);
 
   // Hydrate selection from the URL on mount and respond to back/forward.
   useEffect(() => {
@@ -190,6 +206,28 @@ export default function PlaygroundPage() {
     setPaletteOpen(false);
   }, []);
 
+  // Going back to the index: remember the open method so the index can scroll
+  // it into the center of view rather than resetting to the top.
+  const handleBack = useCallback(() => {
+    pendingScrollRef.current = selection;
+    setLastViewed(selection);
+    setSelection(null);
+  }, [selection]);
+
+  useIsoLayoutEffect(() => {
+    if (selection !== null) return;
+    const target = pendingScrollRef.current;
+    pendingScrollRef.current = null;
+    if (!target?.method) return;
+    const el = document.querySelector(
+      `[data-testid="method-${target.service}-${target.method}"]`,
+    );
+    if (el instanceof HTMLElement) {
+      el.scrollIntoView({ block: "center" });
+      el.focus({ preventScroll: true });
+    }
+  }, [selection]);
+
   const handleRunTests = useCallback(
     async (mode: "all" | "safe") => {
       if (isTestRunning) return;
@@ -305,7 +343,7 @@ export default function PlaygroundPage() {
           </p>
           <ServiceTable
             services={services}
-            activeMethod={selection}
+            activeMethod={selection ?? lastViewed}
             testResults={testResults}
             onSelect={(s, m) => setSelection({ service: s, method: m })}
           />
@@ -318,7 +356,7 @@ export default function PlaygroundPage() {
               isRunning={isTestRunning}
               onRun={handleRunDiagnosis}
               onStop={handleStopTests}
-              onBack={() => setSelection(null)}
+              onBack={handleBack}
             />
           ) : isAutoTest ? (
             <AutoTestView
@@ -328,13 +366,13 @@ export default function PlaygroundPage() {
               onRun={handleRunTests}
               onStop={handleStopTests}
               onRetry={handleRetryTest}
-              onBack={() => setSelection(null)}
+              onBack={handleBack}
             />
           ) : selection ? (
             <MethodView
               service={selection.service}
               method={selection.method}
-              onBack={() => setSelection(null)}
+              onBack={handleBack}
             />
           ) : (
             <div className="empty-state">

playground/src/components/ExampleEditor.tsx

@@ -3,14 +3,21 @@
 import dynamic from "next/dynamic";
 import { useEffect, useState } from "react";
 import {
+  configureLoader,
   MONACO_THEME_DARK,
   MONACO_THEME_LIGHT,
   setupMonaco,
 } from "@/src/lib/monaco-setup";
 import type { Monaco } from "@monaco-editor/react";
 
+// Configure the loader to use the bundled monaco-editor before the Editor
+// component mounts and calls loader.init(), so it never falls back to the CDN.
 const Editor = dynamic(
-  async () => (await import("@monaco-editor/react")).default,
+  async () => {
+    const mod = await import("@monaco-editor/react");
+    await configureLoader();
+    return mod.default;
+  },
   { ssr: false },
 );
 

playground/src/lib/monaco-setup.ts

@@ -1,15 +1,42 @@
 import type { Monaco } from "@monaco-editor/react";
 import { loader } from "@monaco-editor/react";
+import type { Environment } from "monaco-editor";
 import { truapiDts } from "@parity/truapi/playground/codegen/truapi-dts";
 import { rxjsFiles } from "./codegen/rxjs-dts";
 
 export const MONACO_THEME_LIGHT = "truapi-light";
 export const MONACO_THEME_DARK = "truapi-dark";
 
+// Bundle the web workers from the local `monaco-editor` package. Without this,
+// the editor falls back to the AMD loader's `require.toUrl`, which the ESM
+// build does not provide (TypeError: reading 'toUrl'). webpack emits each
+// `new Worker(new URL(...))` as its own chunk served from our own origin.
+function monacoWorker(label: string): Worker {
+  if (label === "typescript" || label === "javascript") {
+    return new Worker(
+      new URL(
+        "monaco-editor/esm/vs/language/typescript/ts.worker.js",
+        import.meta.url,
+      ),
+    );
+  }
+  return new Worker(
+    new URL("monaco-editor/esm/vs/editor/editor.worker.js", import.meta.url),
+  );
+}
+
 let loaderConfigured = false;
-async function configureLoader(): Promise<void> {
+/**
+ * Point `@monaco-editor/react`'s loader at the bundled `monaco-editor` package
+ * instead of its default jsdelivr CDN. Must run before the Editor mounts and
+ * calls `loader.init()`, otherwise the loader falls back to the CDN.
+ */
+export async function configureLoader(): Promise<void> {
   if (loaderConfigured) return;
   loaderConfigured = true;
+  (
+    globalThis as typeof globalThis & { MonacoEnvironment?: Environment }
+  ).MonacoEnvironment = { getWorker: (_id, label) => monacoWorker(label) };
   // Lazy-import monaco-editor on the client only. Importing it eagerly at
   // module scope crashes Next's SSR prerender (`window is not defined`).
   const monaco = await import("monaco-editor");