docs: Multiple files support (#989)

* Reading multiple files into dictionaries
* Editor now has tabs
* Type example holds now all possible data regarding examples

* Introduced TS bundler

* Removed legacy live preview code

* Working static imports

* Fixed StackBlitz, added onCleanup

* Astro tgpu quick fix

* Dynamic import fix endeavour

* No cache import implemented

* Types fixes

* Minor type fixes, biome suggested fixes

* Moved .html control files to the file tabs

* Naming changes

* Moved filtering out of context for readability

* Fixed mobile version

* Tidying

* Biome formatting fixes

* Pull request fixes

* Creating URL instead of plain string for ViteImport

* Fixed relative pathing in vite's build

* PR final fixes

* Formatting changes

* Monaco css endeavour

* Fixed wrong default file in monaco bug

* Fixed css monaco issue

* Naming tsSources -> tsImports

* CSS Monaco final fix

block h-[calc(100%-6rem)] md:h-[calc(100%-2rem)] was the correct answer

* Vite ignore fixes

* Run babel

* Biome fix

* Block is default expression

* Not checking whether index.ts exists anymore

Author: lursz

apps/typegpu-docs/astro.config.mjs

@@ -18,38 +18,12 @@ const stripFalsy = (items) =>
 
 const DEV = import.meta.env.DEV;
 
-/**
- * Plugin that converts code transformed by the `typegpu` plugin to a raw string.
- * @returns {{
- *   name: string;
- *   enforce: 'post';
- *   transform(code: string, id: string): { code: string } | undefined;
- * }}
- */
-function toRawPlugin() {
-  return {
-    name: 'to-raw',
-    enforce: 'post',
-
-    transform(code, id) {
-      if (id.endsWith('?tgpu=true')) {
-        return {
-          code: `export default ${JSON.stringify(code)
-            .replace(/\u2028/g, '\\u2028')
-            .replace(/\u2029/g, '\\u2029')};`,
-        };
-      }
-      return undefined;
-    },
-  };
-}
-
 // https://astro.build/config
 export default defineConfig({
   site: 'https://docs.swmansion.com',
   base: 'TypeGPU',
   vite: {
-    plugins: [typegpu({ include: [/tgpu=true/] }), toRawPlugin()],
+    plugins: [typegpu({ include: [/tgpu=true/] })],
   },
   integrations: [
     starlight({

apps/typegpu-docs/package.json

@@ -15,7 +15,6 @@
     "@astrojs/starlight": "^0.32.1",
     "@astrojs/starlight-tailwind": "^3.0.0",
     "@astrojs/tailwind": "^6.0.0",
-    "@babel/standalone": "^7.26.6",
     "@monaco-editor/react": "^4.6.0",
     "@radix-ui/react-select": "^2.1.1",
     "@radix-ui/react-slider": "^1.2.0",

apps/typegpu-docs/src/components/CodeEditor.tsx

@@ -90,7 +90,11 @@ const createCodeEditorComponent =
     const { code, shown } = props;
 
     return (
-      <div className={shown ? 'contents' : 'hidden'}>
+      <div
+        className={
+          shown ? 'h-[calc(100%-6rem)] md:h-[calc(100%-2rem)]' : 'hidden'
+        }
+      >
         <Editor
           defaultLanguage={language}
           value={code}
@@ -102,7 +106,7 @@ const createCodeEditorComponent =
             },
             readOnly: true,
           }}
-          className="pt-16 md:pt-0"
+          className="rounded-tl-none"
         />
       </div>
     );

apps/typegpu-docs/src/components/ExampleView.tsx

@@ -22,7 +22,7 @@ type Props = {
 };
 
 function useExample(
-  exampleCode: string,
+  tsImports: Record<string, () => Promise<unknown>>,
   htmlCode: string,
   setSnackbarText: (text: string | undefined) => void,
 ) {
@@ -34,14 +34,13 @@ function useExample(
     let cancelled = false;
     setSnackbarText(undefined);
 
-    executeExample(exampleCode)
+    executeExample(tsImports)
       .then((example) => {
         if (cancelled) {
           // Another instance was started in the meantime.
           example.dispose();
           return;
         }
-
         // Success
         setExampleControlParams(example.controlParams);
         exampleRef.current = example;
@@ -63,32 +62,35 @@ function useExample(
       exampleRef.current?.dispose();
       cancelled = true;
     };
-  }, [exampleCode, htmlCode, setSnackbarText, setExampleControlParams]);
+  }, [htmlCode, setSnackbarText, setExampleControlParams]);
 }
 
-type EditorTab = 'ts' | 'html';
-
 export function ExampleView({ example }: Props) {
-  const { tsCode, htmlCode, execTsCode } = example;
+  const { tsCodes, tsImports, htmlCode } = example;
 
   const [snackbarText, setSnackbarText] = useAtom(currentSnackbarAtom);
-  const [currentEditorTab, setCurrentEditorTab] = useState<EditorTab>('ts');
+  const [currentFile, setCurrentFile] = useState<string>('index.ts');
 
   const codeEditorShowing = useAtomValue(codeEditorShownAtom);
   const codeEditorMobileShowing = useAtomValue(codeEditorShownMobileAtom);
-
   const exampleHtmlRef = useRef<HTMLDivElement>(null);
 
-  // biome-ignore lint/correctness/useExhaustiveDependencies: reset embedded html on code change
+  const codeFiles = Object.keys(tsCodes);
+  const editorTabsList = [
+    'index.ts',
+    ...codeFiles.filter((name) => name !== 'index.ts'),
+    'index.html',
+  ];
+
   useEffect(() => {
     if (!exampleHtmlRef.current) {
       return;
     }
     exampleHtmlRef.current.innerHTML = htmlCode;
-  }, [tsCode, htmlCode]);
+  }, [htmlCode]);
 
-  useExample(execTsCode, htmlCode, setSnackbarText);
-  useResizableCanvas(exampleHtmlRef, tsCode, htmlCode);
+  useExample(tsImports, htmlCode, setSnackbarText); // live example
+  useResizableCanvas(exampleHtmlRef, htmlCode);
 
   return (
     <>
@@ -97,7 +99,7 @@ export function ExampleView({ example }: Props) {
       <div className="flex flex-col md:grid gap-4 md:grid-cols-[1fr_18.75rem] h-full">
         <div
           className={cs(
-            'flex-1 grid gap-4 overflow-auto',
+            'flex-1 grid gap-4',
             codeEditorShowing ? 'md:grid-rows-2' : '',
           )}
         >
@@ -131,18 +133,29 @@ export function ExampleView({ example }: Props) {
                 'absolute bg-tameplum-50 z-20 md:relative h-[calc(100%-2rem)] w-[calc(100%-2rem)] md:w-full md:h-full',
               )}
             >
-              <div className="absolute inset-0">
-                <EditorTabButtonPanel
-                  currentEditorTab={currentEditorTab}
-                  setCurrentEditorTab={setCurrentEditorTab}
-                />
-
-                <TsCodeEditor shown={currentEditorTab === 'ts'} code={tsCode} />
-
-                <HtmlCodeEditor
-                  shown={currentEditorTab === 'html'}
-                  code={htmlCode}
-                />
+              <div className="absolute inset-1">
+                <div className="flex overflow-auto border-gray-300 pt-16 md:pt-0">
+                  {editorTabsList.map((fileName) => (
+                    <button
+                      key={fileName}
+                      type="button"
+                      onClick={() => setCurrentFile(fileName)}
+                      className={cs(
+                        'px-4 py-2',
+                        currentFile === fileName
+                          ? 'rounded-t-lg rounded-bl-none rounded-br-none bg-gradient-to-br from-gradient-purple to-gradient-blue text-white hover:from-gradient-purple-dark hover:to-gradient-blue-dark'
+                          : 'rounded-t-lg rounded-bl-none rounded-br-none bg-white border-tameplum-100 border-2 hover:bg-tameplum-20',
+                      )}
+                    >
+                      {fileName}
+                    </button>
+                  ))}
+                </div>
+                {currentFile === 'index.html' ? (
+                  <HtmlCodeEditor shown code={htmlCode} />
+                ) : (
+                  <TsCodeEditor shown code={tsCodes[currentFile]} />
+                )}
               </div>
             </div>
           ) : null}
@@ -153,48 +166,6 @@ export function ExampleView({ example }: Props) {
   );
 }
 
-function EditorTabButtonPanel({
-  currentEditorTab,
-  setCurrentEditorTab,
-}: {
-  currentEditorTab: EditorTab;
-  setCurrentEditorTab: (tab: EditorTab) => void;
-}) {
-  const commonStyle =
-    'inline-flex justify-center items-center box-border text-sm px-5 py-1';
-  const activeStyle =
-    'bg-gradient-to-br from-gradient-purple to-gradient-blue text-white hover:from-gradient-purple-dark hover:to-gradient-blue-dark';
-  const inactiveStyle =
-    'bg-white border-tameplum-100 border-2 hover:bg-tameplum-20';
-
-  return (
-    <div className="absolute right-0 md:right-6 top-2 z-10 flex">
-      <button
-        className={cs(
-          commonStyle,
-          'rounded-l-lg',
-          currentEditorTab === 'ts' ? activeStyle : inactiveStyle,
-        )}
-        type="button"
-        onClick={() => setCurrentEditorTab('ts')}
-      >
-        TS
-      </button>
-      <button
-        className={cs(
-          commonStyle,
-          'rounded-r-lg',
-          currentEditorTab === 'html' ? activeStyle : inactiveStyle,
-        )}
-        type="button"
-        onClick={() => setCurrentEditorTab('html')}
-      >
-        HTML
-      </button>
-    </div>
-  );
-}
-
 function GPUUnsupportedPanel() {
   return (
     <div className="grid gap-6 text-xl leading-tight text-center place-content-center">
@@ -215,7 +186,6 @@ function GPUUnsupportedPanel() {
 
 function useResizableCanvas(
   exampleHtmlRef: RefObject<HTMLDivElement | null>,
-  tsCode: string,
   htmlCode: string,
 ) {
   // biome-ignore lint/correctness/useExhaustiveDependencies: should be run on every htmlCode and tsCode change
@@ -276,5 +246,5 @@ function useResizableCanvas(
         observer.disconnect();
       }
     };
-  }, [exampleHtmlRef, tsCode, htmlCode]);
+  }, [exampleHtmlRef, htmlCode]);
 }

apps/typegpu-docs/src/components/stackblitz/openInStackBlitz.ts

@@ -17,16 +17,24 @@ if (pnpmWorkspaceYaml instanceof type.errors) {
 }
 
 export const openInStackBlitz = (example: Example) => {
+  const tsFiles = Object.entries(example.tsCodes).reduce(
+    (acc, [fileName, code]) => {
+      acc[`src/${fileName}`] = code.replaceAll(
+        '/TypeGPU',
+        'https://docs.swmansion.com/TypeGPU',
+      );
+      return acc;
+    },
+    {} as Record<string, string>,
+  );
+
   StackBlitzSDK.openProject(
     {
       template: 'node',
       title: example.metadata.title,
       files: {
         'index.ts': index.slice('// @ts-ignore\n'.length),
-        'src/example.ts': example.tsCode.replaceAll(
-          '/TypeGPU',
-          'https://docs.swmansion.com/TypeGPU',
-        ),
+        ...tsFiles,
         'index.html': `\
 <!DOCTYPE html>
 <html lang="en">
@@ -55,7 +63,7 @@ ${example.htmlCode}
         "noEmit": true,
         "strict": true,
         "noUnusedLocals": true,
-        "noUnusedParameters": true,
+        "noUnusedParameters": true
     },
     "include": ["src", "index.ts"]
 }`,
@@ -91,7 +99,7 @@ export default defineConfig({
       },
     },
     {
-      openFile: 'src/example.ts',
+      openFile: 'src/index.ts',
       newWindow: true,
       theme: 'light',
     },

apps/typegpu-docs/src/components/stackblitz/stackBlitzIndex.ts

@@ -1,5 +1,5 @@
 // @ts-ignore
-import * as example from './src/example.ts';
+import * as example from './src/index.ts';
 
 const body = document.querySelector('body') as HTMLBodyElement;
 body.style.display = 'flex';

apps/typegpu-docs/src/content/examples/simple/triangle/index.ts

@@ -5,6 +5,9 @@ const presentationFormat = navigator.gpu.getPreferredCanvasFormat();
 const canvas = document.querySelector('canvas') as HTMLCanvasElement;
 const context = canvas.getContext('webgpu') as GPUCanvasContext;
 
+const purple = d.vec4f(0.769, 0.392, 1.0, 1);
+const blue = d.vec4f(0.114, 0.447, 0.941, 1);
+
 const root = await tgpu.init();
 
 context.configure({
@@ -13,9 +16,6 @@ context.configure({
   alphaMode: 'premultiplied',
 });
 
-const purple = d.vec4f(0.769, 0.392, 1.0, 1);
-const blue = d.vec4f(0.114, 0.447, 0.941, 1);
-
 const getGradientColor = tgpu['~unstable']
   .fn([d.f32], d.vec4f)
   .does(/* wgsl */ `(ratio: f32) -> vec4f {