docs: Common code between examples (#1995)

Author: aleksanderkatan

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

@@ -6,7 +6,10 @@ import Editor, {
 import type { editor } from 'monaco-editor';
 import { entries, filter, fromEntries, isTruthy, map, pipe } from 'remeda';
 import { SANDBOX_MODULES } from '../utils/examples/sandboxModules.ts';
-import type { ExampleSrcFile } from '../utils/examples/types.ts';
+import type {
+  ExampleCommonFile,
+  ExampleSrcFile,
+} from '../utils/examples/types.ts';
 import { tsCompilerOptions } from '../utils/liveEditor/embeddedTypeScript.ts';
 
 function handleEditorWillMount(monaco: Monaco) {
@@ -56,7 +59,7 @@ function handleEditorOnMount(editor: editor.IStandaloneCodeEditor) {
 }
 
 type Props = {
-  file: ExampleSrcFile;
+  file: ExampleSrcFile | ExampleCommonFile;
   shown: boolean;
 };
 
@@ -68,6 +71,11 @@ const createCodeEditorComponent = (
 (props: Props) => {
   const { file, shown } = props;
 
+  // Monaco needs relative paths to work correctly and '../../common/file.ts' will not do
+  const path = 'common' in file
+    ? `common/${file.path}`
+    : `${file.exampleKey.replace('--', '/')}/${file.path}`;
+
   return (
     <div
       className={shown
@@ -77,7 +85,7 @@ const createCodeEditorComponent = (
       <Editor
         defaultLanguage={language}
         value={file.content}
-        path={file.path}
+        path={path}
         beforeMount={beforeMount}
         onMount={onMount}
         options={{

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

@@ -1,7 +1,7 @@
 import { useAtomValue, useSetAtom } from 'jotai';
 import { Suspense, useEffect, useRef } from 'react';
 import { currentExampleAtom } from '../utils/examples/currentExampleAtom.ts';
-import { examples } from '../examples/exampleContent.ts';
+import { common, examples } from '../examples/exampleContent.ts';
 import { ExampleNotFound } from './ExampleNotFound.tsx';
 import { ExampleView } from './ExampleView.tsx';
 
@@ -68,7 +68,11 @@ function ExamplePage() {
 
     if (currentExample in examples) {
       return (
-        <ExampleView key={currentExample} example={examples[currentExample]} />
+        <ExampleView
+          key={currentExample}
+          example={examples[currentExample]}
+          common={common}
+        />
       );
     }
 

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

@@ -10,7 +10,11 @@ import { ExecutionCancelledError } from '../utils/examples/errors.ts';
 import { exampleControlsAtom } from '../utils/examples/exampleControlAtom.ts';
 import { executeExample } from '../utils/examples/exampleRunner.ts';
 import type { ExampleState } from '../utils/examples/exampleState.ts';
-import type { Example } from '../utils/examples/types.ts';
+import type {
+  Example,
+  ExampleCommonFile,
+  ExampleSrcFile,
+} from '../utils/examples/types.ts';
 import { isGPUSupported } from '../utils/isGPUSupported.ts';
 import { HtmlCodeEditor, TsCodeEditor } from './CodeEditor.tsx';
 import { ControlPanel } from './ControlPanel.tsx';
@@ -20,6 +24,7 @@ import { openInStackBlitz } from './stackblitz/openInStackBlitz.ts';
 
 type Props = {
   example: Example;
+  common: ExampleCommonFile[];
   isPlayground?: boolean;
 };
 
@@ -66,8 +71,8 @@ function useExample(
   }, [setSnackbarText, setExampleControlParams]);
 }
 
-export function ExampleView({ example }: Props) {
-  const { tsFiles, tsImport, htmlFile } = example;
+export function ExampleView({ example, common }: Props) {
+  const { tsFiles: srcFiles, tsImport, htmlFile } = example;
 
   const [snackbarText, setSnackbarText] = useAtom(currentSnackbarAtom);
   const [currentFilePath, setCurrentFilePath] = useState<string>('index.ts');
@@ -76,6 +81,7 @@ export function ExampleView({ example }: Props) {
   const codeEditorMobileShowing = useAtomValue(codeEditorShownMobileAtom);
   const exampleHtmlRef = useRef<HTMLDivElement>(null);
 
+  const tsFiles = filterRelevantTsFiles(srcFiles, common);
   const filePaths = tsFiles.map((file) => file.path);
   const editorTabsList = [
     'index.ts',
@@ -171,7 +177,7 @@ export function ExampleView({ example }: Props) {
                 </div>
 
                 <div className='absolute right-0 z-5 md:top-15 md:right-8'>
-                  <Button onClick={() => openInStackBlitz(example)}>
+                  <Button onClick={() => openInStackBlitz(example, common)}>
                     <span className='font-bold'>Edit on</span>
                     <img
                       src='https://developer.stackblitz.com/img/logo/stackblitz-logo-black_blue.svg'
@@ -290,3 +296,27 @@ function useResizableCanvas(exampleHtmlRef: RefObject<HTMLDivElement | null>) {
     };
   }, [exampleHtmlRef]);
 }
+
+/**
+ * NOTE: this function only filters common files used in src files.
+ * Common files used in other common files will not be included.
+ */
+function filterRelevantTsFiles(
+  srcFiles: ExampleSrcFile[],
+  commonFiles: ExampleCommonFile[],
+) {
+  const tsFiles: (ExampleSrcFile | ExampleCommonFile)[] = [
+    ...srcFiles,
+  ];
+
+  for (const common of commonFiles) {
+    for (const src of srcFiles) {
+      if (src.content.includes(`common/${common.path}`)) {
+        tsFiles.push(common);
+        break;
+      }
+    }
+  }
+
+  return tsFiles;
+}

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

@@ -19,7 +19,7 @@ import pnpmWorkspace from '../../../../../pnpm-workspace.yaml?raw';
 import typegpuDocsPackageJson from '../../../package.json' with {
   type: 'json',
 };
-import type { Example } from '../../utils/examples/types.ts';
+import type { Example, ExampleCommonFile } from '../../utils/examples/types.ts';
 // biome-ignore lint/correctness/useImportExtensions: dude it's there
 import index from './stackBlitzIndex.ts?raw';
 
@@ -51,17 +51,29 @@ if (pnpmWorkspaceYaml instanceof type.errors) {
   throw new Error(pnpmWorkspaceYaml.summary);
 }
 
-export const openInStackBlitz = (example: Example) => {
-  const tsFiles = example.tsFiles.reduce(
-    (acc, file) => {
-      acc[`src/${file.path}`] = file.content.replaceAll(
-        '/TypeGPU',
-        'https://docs.swmansion.com/TypeGPU',
-      );
-      return acc;
-    },
-    {} as Record<string, string>,
-  );
+export const openInStackBlitz = (
+  example: Example,
+  common: ExampleCommonFile[],
+) => {
+  const tsFiles: Record<string, string> = {};
+
+  for (const file of example.tsFiles) {
+    tsFiles[`src/${file.path}`] = file.content;
+  }
+  for (const file of common) {
+    tsFiles[`src/common/${file.path}`] = file.content;
+  }
+
+  for (const key of Object.keys(tsFiles)) {
+    const content = tsFiles[key];
+    tsFiles[key] = content.replaceAll(
+      '/TypeGPU',
+      'https://docs.swmansion.com/TypeGPU',
+    ).replaceAll(
+      '../../common',
+      './common',
+    );
+  }
 
   StackBlitzSDK.openProject(
     {

…g/phong-reflection/setup-orbit-camera.ts …rc/examples/common/setup-orbit-camera.tsapps/typegpu-docs/src/examples/rendering/phong-reflection/setup-orbit-camera.ts renamed to apps/typegpu-docs/src/examples/common/setup-orbit-camera.ts apps/typegpu-docs/src/examples/rendering/phong-reflection/setup-orbit-camera.ts renamed to apps/typegpu-docs/src/examples/common/setup-orbit-camera.ts

@@ -2,6 +2,7 @@ import pathe from 'pathe';
 import * as R from 'remeda';
 import type {
   Example,
+  ExampleCommonFile,
   ExampleMetadata,
   ExampleSrcFile,
   ThumbnailPair,
@@ -75,8 +76,9 @@ const metaFiles = R.pipe(
   R.mapKeys(pathToExampleKey),
 );
 
-const readonlyTsFiles = R.pipe(
-  import.meta.glob('./**/*.ts', {
+const exampleTsFiles = R.pipe(
+  // './<category>/<example>/<file>.ts'
+  import.meta.glob('./*/*/*.ts', {
     query: 'raw',
     eager: true,
     import: 'default',
@@ -127,7 +129,7 @@ export const examples = R.pipe(
     ({
       key,
       metadata: value,
-      tsFiles: readonlyTsFiles[key] ?? [],
+      tsFiles: exampleTsFiles[key] ?? [],
       tsImport: () => noCacheImport(tsFilesImportFunctions[key]),
       htmlFile: htmlFiles[key]?.[0] ?? '',
       thumbnails: thumbnailFiles[key],
@@ -140,4 +142,18 @@ export const examplesByCategory = R.groupBy(
   (example) => example.metadata.category,
 );
 
+export const common = R.pipe(
+  import.meta.glob('./common/*.ts', {
+    query: 'raw',
+    eager: true,
+    import: 'default',
+  }) as Record<string, string>,
+  R.mapValues((content: string, key: string): ExampleCommonFile => ({
+    common: true,
+    path: pathe.basename(key),
+    content,
+  })),
+  R.values(),
+);
+
 export const PLAYGROUND_KEY = 'playground__';

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

@@ -9,7 +9,7 @@ import {
   ModelVertexOutput,
 } from './schemas.ts';
 import { loadModel } from './load-model.ts';
-import { Camera, setupOrbitCamera } from './setup-orbit-camera.ts';
+import { Camera, setupOrbitCamera } from '../../common/setup-orbit-camera.ts';
 
 // setup
 const canvas = document.querySelector('canvas') as HTMLCanvasElement;
@@ -46,7 +46,7 @@ const exampleControlsUniform = root.createUniform(
   p.initialControls,
 );
 
-export const vertexShader = tgpu['~unstable'].vertexFn({
+const vertexShader = tgpu['~unstable'].vertexFn({
   in: { ...ModelVertexInput.propTypes, instanceIndex: d.builtin.instanceIndex },
   out: ModelVertexOutput,
 })((input) => {
@@ -63,7 +63,7 @@ export const vertexShader = tgpu['~unstable'].vertexFn({
 });
 
 // see https://gist.github.com/chicio/d983fff6ff304bd55bebd6ff05a2f9dd
-export const fragmentShader = tgpu['~unstable'].fragmentFn({
+const fragmentShader = tgpu['~unstable'].fragmentFn({
   in: ModelVertexOutput,
   out: d.vec4f,
 })((input) => {

apps/typegpu-docs/src/examples/rendering/phong-reflection/index.ts

@@ -39,7 +39,7 @@ import {
   Time,
   timeAccess,
 } from './schemas.ts';
-import { Camera, setupOrbitCamera } from './setup-orbit-camera.ts';
+import { Camera, setupOrbitCamera } from '../../common/setup-orbit-camera.ts';
 
 const presentationFormat = navigator.gpu.getPreferredCanvasFormat();
 const canvas = document.querySelector('canvas') as HTMLCanvasElement;

apps/typegpu-docs/src/examples/simulation/gravity/index.ts

@@ -1,6 +1,6 @@
 import tgpu, { type TgpuSampler } from 'typegpu';
 import * as d from 'typegpu/data';
-import { Camera } from './setup-orbit-camera.ts';
+import { Camera } from '../../common/setup-orbit-camera.ts';
 
 export type CelestialBody = d.Infer<typeof CelestialBody>;
 export const CelestialBody = d.struct({