fix(typegpu-docs): Cross file import types (#1142)

Author: iwoplaza

apps/typegpu-docs/package.json

@@ -22,13 +22,13 @@
     "@radix-ui/react-slider": "^1.2.0",
     "@stackblitz/sdk": "^1.11.0",
     "@std/yaml": "npm:@jsr/std__yaml@^1.0.5",
-    "@typegpu/noise": "workspace:*",
     "@typegpu/color": "workspace:*",
+    "@typegpu/noise": "workspace:*",
     "@types/dom-mediacapture-transform": "^0.1.9",
     "@types/react": "^19.0.10",
     "@types/react-dom": "^19.0.4",
-    "astro": "^5.3.1",
     "arktype": "catalog:",
+    "astro": "^5.3.1",
     "classnames": "^2.5.1",
     "expressive-code-twoslash": "^0.4.0",
     "jotai": "^2.8.4",
@@ -37,6 +37,7 @@
     "lz-string": "^1.5.0",
     "monaco-editor": "^0.52.2",
     "motion": "^12.4.5",
+    "pathe": "^2.0.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "remeda": "^2.21.2",

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

@@ -7,6 +7,7 @@ import Editor, {
 import type { editor } from 'monaco-editor';
 import { entries, filter, fromEntries, isTruthy, map, pipe } from 'remeda';
 import { SANDBOX_MODULES } from '../utils/examples/sandboxModules';
+import type { ExampleSrcFile } from '../utils/examples/types';
 import { tsCompilerOptions } from '../utils/liveEditor/embeddedTypeScript';
 
 function handleEditorWillMount(monaco: Monaco) {
@@ -56,7 +57,7 @@ function handleEditorOnMount(editor: editor.IStandaloneCodeEditor) {
 }
 
 type Props = {
-  code: string;
+  file: ExampleSrcFile;
   shown: boolean;
 };
 
@@ -67,7 +68,7 @@ const createCodeEditorComponent =
     onMount?: OnMount,
   ) =>
   (props: Props) => {
-    const { code, shown } = props;
+    const { file, shown } = props;
 
     return (
       <div
@@ -77,7 +78,8 @@ const createCodeEditorComponent =
       >
         <Editor
           defaultLanguage={language}
-          value={code}
+          value={file.content}
+          path={file.path}
           beforeMount={beforeMount}
           onMount={onMount}
           options={{

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

@@ -23,7 +23,6 @@ type Props = {
 
 function useExample(
   tsImport: () => Promise<unknown>,
-  htmlCode: string,
   setSnackbarText: (text: string | undefined) => void,
 ) {
   const exampleRef = useRef<ExampleState | null>(null);
@@ -62,35 +61,35 @@ function useExample(
       exampleRef.current?.dispose();
       cancelled = true;
     };
-  }, [htmlCode, setSnackbarText, setExampleControlParams]);
+  }, [setSnackbarText, setExampleControlParams]);
 }
 
 export function ExampleView({ example }: Props) {
-  const { tsCodes, tsImport, htmlCode } = example;
+  const { tsFiles, tsImport, htmlFile } = example;
 
   const [snackbarText, setSnackbarText] = useAtom(currentSnackbarAtom);
-  const [currentFile, setCurrentFile] = useState<string>('index.ts');
+  const [currentFilePath, setCurrentFilePath] = useState<string>('index.ts');
 
   const codeEditorShowing = useAtomValue(codeEditorShownAtom);
   const codeEditorMobileShowing = useAtomValue(codeEditorShownMobileAtom);
   const exampleHtmlRef = useRef<HTMLDivElement>(null);
 
-  const codeFiles = Object.keys(tsCodes);
+  const filePaths = tsFiles.map((file) => file.path);
   const editorTabsList = [
     'index.ts',
-    ...codeFiles.filter((name) => name !== 'index.ts'),
+    ...filePaths.filter((name) => name !== 'index.ts'),
     'index.html',
   ];
 
   useEffect(() => {
     if (!exampleHtmlRef.current) {
       return;
     }
-    exampleHtmlRef.current.innerHTML = htmlCode;
-  }, [htmlCode]);
+    exampleHtmlRef.current.innerHTML = htmlFile.content;
+  }, [htmlFile]);
 
-  useExample(tsImport, htmlCode, setSnackbarText); // live example
-  useResizableCanvas(exampleHtmlRef, htmlCode);
+  useExample(tsImport, setSnackbarText); // live example
+  useResizableCanvas(exampleHtmlRef);
 
   return (
     <>
@@ -140,10 +139,10 @@ export function ExampleView({ example }: Props) {
                       <button
                         key={fileName}
                         type="button"
-                        onClick={() => setCurrentFile(fileName)}
+                        onClick={() => setCurrentFilePath(fileName)}
                         className={cs(
                           'px-4 rounded-t-lg rounded-b-none text-nowrap',
-                          currentFile === fileName
+                          currentFilePath === fileName
                             ? 'bg-gradient-to-br from-gradient-purple to-gradient-blue text-white hover:from-gradient-purple-dark hover:to-gradient-blue-dark'
                             : 'bg-white border-tameplum-100 border-2 hover:bg-tameplum-20',
                         )}
@@ -155,15 +154,15 @@ export function ExampleView({ example }: Props) {
                 </div>
 
                 <HtmlCodeEditor
-                  shown={currentFile === 'index.html'}
-                  code={htmlCode}
+                  shown={currentFilePath === 'index.html'}
+                  file={htmlFile}
                 />
 
-                {Object.entries(tsCodes).map(([key, value]) => (
+                {tsFiles.map((file) => (
                   <TsCodeEditor
-                    shown={key === currentFile}
-                    code={value}
-                    key={key}
+                    key={file.path}
+                    shown={file.path === currentFilePath}
+                    file={file}
                   />
                 ))}
               </div>
@@ -194,11 +193,7 @@ function GPUUnsupportedPanel() {
   );
 }
 
-function useResizableCanvas(
-  exampleHtmlRef: RefObject<HTMLDivElement | null>,
-  htmlCode: string,
-) {
-  // biome-ignore lint/correctness/useExhaustiveDependencies: should be run on every htmlCode and tsCode change
+function useResizableCanvas(exampleHtmlRef: RefObject<HTMLDivElement | null>) {
   useEffect(() => {
     const canvases = exampleHtmlRef.current?.querySelectorAll('canvas') as
       | HTMLCanvasElement[]
@@ -261,5 +256,5 @@ function useResizableCanvas(
         observer.disconnect();
       }
     };
-  }, [exampleHtmlRef, htmlCode]);
+  }, [exampleHtmlRef]);
 }

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

@@ -19,9 +19,9 @@ 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(
+  const tsFiles = example.tsFiles.reduce(
+    (acc, file) => {
+      acc[`src/${file.path}`] = file.content.replaceAll(
         '/TypeGPU',
         'https://docs.swmansion.com/TypeGPU',
       );
@@ -46,7 +46,7 @@ export const openInStackBlitz = (example: Example) => {
     <title>${example.metadata.title}</title>
 </head>
 <body>
-${example.htmlCode}
+${example.htmlFile.content}
 <script type="module" src="/index.ts"></script>
 </body>
 </html>`,

apps/typegpu-docs/src/utils/examples/exampleContent.ts

@@ -1,111 +1,105 @@
-import { entries, filter, fromEntries, groupBy, map, pipe } from 'remeda';
-import type { Example, ExampleMetadata } from './types';
+import pathe from 'pathe';
+import * as R from 'remeda';
+import type { Example, ExampleMetadata, ExampleSrcFile } from './types';
 
-function pathPipe(path: string): string {
-  return pipe(
+const contentExamplesPath = '../../content/examples/';
+
+function pathToExampleKey(path: string): string {
+  return R.pipe(
     path,
-    (p) => p.replace(/^..\/..\/content\/examples\//, ''), // removing parent folder
-    (p) => p.replace(/\/[^\/]*$/, ''), // removing leaf file names (e.g. meta.json, index.ts)
-    (p) => p.replace(/\//, '--'), // replacing path separators with '--'
+    (p) => pathe.relative(contentExamplesPath, p), // removing parent folder
+    (p) => p.split('/'), // splitting into segments
+    ([category, name]) => `${category}--${name}`,
   );
 }
 
-function pathToExampleKey<T>(record: Record<string, T>): Record<string, T> {
-  return pipe(
+function globToExampleFiles(
+  record: Record<string, string>,
+): Record<string, ExampleSrcFile[]> {
+  return R.pipe(
     record,
-    entries(),
-    map(([path, value]) => [pathPipe(path), value] as const),
-    fromEntries(),
-  );
-}
-
-function pathToExampleFilesMap<T>(
-  record: Record<string, T>,
-): Record<string, Record<string, T>> {
-  const groups: Record<string, Record<string, T>> = {};
+    R.mapValues((content, key): ExampleSrcFile => {
+      const pathRelToExamples = pathe.relative(contentExamplesPath, key);
+      const categoryDir = pathRelToExamples.split('/')[0];
+      const exampleDir = pathRelToExamples.split('/')[1];
+      const examplePath = pathe.join(
+        contentExamplesPath,
+        categoryDir,
+        exampleDir,
+      );
 
-  for (const [path, value] of Object.entries(record)) {
-    const groupKey = pathPipe(path);
-
-    const fileNameMatch = path.match(/\/([^\/]+\.ts)$/);
-    const fileName = fileNameMatch ? fileNameMatch[1] : path;
-
-    if (!groups[groupKey]) {
-      groups[groupKey] = {};
-    }
-    groups[groupKey][fileName] = value;
-  }
-  return groups;
+      return {
+        exampleKey: pathToExampleKey(key),
+        path: pathe.relative(examplePath, key),
+        content,
+      };
+    }),
+    R.values(),
+    R.groupBy(R.prop('exampleKey')),
+  );
 }
 
-const metaFiles: Record<string, ExampleMetadata> = pathToExampleKey(
+const metaFiles = R.pipe(
   import.meta.glob('../../content/examples/**/meta.json', {
     eager: true,
     import: 'default',
-  }),
+  }) as Record<string, ExampleMetadata>,
+  R.mapKeys(pathToExampleKey),
 );
 
-const readonlyTsFiles: Record<
-  string,
-  Record<string, string>
-> = pathToExampleFilesMap(
+const readonlyTsFiles = R.pipe(
   import.meta.glob('../../content/examples/**/*.ts', {
     query: 'raw',
     eager: true,
     import: 'default',
-  }),
+  }) as Record<string, string>,
+  globToExampleFiles,
 );
 
-const tsFilesImportFunctions: Record<string, () => Promise<unknown>> = pipe(
-  import.meta.glob('../../content/examples/**/index.ts'),
-  entries(),
-  map(
-    ([key, value]) =>
-      [pathPipe(key), value] satisfies [string, () => Promise<unknown>],
-  ),
-  fromEntries(),
+const tsFilesImportFunctions = R.pipe(
+  import.meta.glob('../../content/examples/**/index.ts') as Record<
+    string,
+    () => Promise<unknown>
+  >,
+  R.mapKeys(pathToExampleKey),
 );
 
-const htmlFiles: Record<string, string> = pathToExampleKey(
+const htmlFiles = R.pipe(
   import.meta.glob('../../content/examples/**/index.html', {
     query: 'raw',
     eager: true,
     import: 'default',
-  }),
+  }) as Record<string, string>,
+  globToExampleFiles,
 );
 
-export const examples = pipe(
+export const examples = R.pipe(
   metaFiles,
-  entries(),
-  map(
-    ([key, value]) =>
-      [
+  R.mapValues(
+    (value, key) =>
+      ({
         key,
-        {
-          key,
-          metadata: value,
-          tsCodes: readonlyTsFiles[key] ?? {},
-          tsImport: tsFilesImportFunctions[key],
-          htmlCode: htmlFiles[key] ?? '',
-        },
-      ] satisfies [string, Example],
+        metadata: value,
+        tsFiles: readonlyTsFiles[key] ?? [],
+        tsImport: tsFilesImportFunctions[key],
+        htmlFile: htmlFiles[key][0] ?? '',
+      }) satisfies Example,
   ),
-  fromEntries(),
 );
 
-export const examplesStable = pipe(
+export const examplesStable = R.pipe(
   examples,
-  entries(),
-  filter(([_, example]) => !example.metadata.tags?.includes('experimental')),
-  filter(([_, example]) =>
+  R.entries(),
+  R.filter(([_, example]) => !example.metadata.tags?.includes('experimental')),
+  R.filter(([_, example]) =>
     example.metadata.tags?.includes('camera')
       ? typeof MediaStreamTrackProcessor === 'undefined'
       : true,
   ),
-  fromEntries(),
+  R.fromEntries(),
 );
 
-export const examplesByCategory = groupBy(
+export const examplesByCategory = R.groupBy(
   Object.values(examples),
   (example) => example.metadata.category,
 );

apps/typegpu-docs/src/utils/examples/types.ts

@@ -16,14 +16,16 @@ export const exampleCategories = [
   { key: 'tests', label: 'Tests' },
 ];
 
+export type ExampleSrcFile = {
+  exampleKey: string;
+  path: string;
+  content: string;
+};
+
 export type Example = {
   key: string;
-  tsCodes: Record<string, string>;
+  tsFiles: ExampleSrcFile[];
   tsImport: () => Promise<unknown>;
-  htmlCode: string;
+  htmlFile: ExampleSrcFile;
   metadata: ExampleMetadata;
 };
-
-export type Module = {
-  default: string;
-};