Add tags to examples and hide those marked as experimental (#316)

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

@@ -5,6 +5,8 @@ import { menuShownAtom } from '../utils/examples/menuShownAtom';
 import ExampleList from './ExampleList';
 import ExamplePage from './ExamplePage';
 
+const isDev = import.meta.env.DEV;
+
 export function ExampleLayout() {
   const menuShown = useAtomValue(menuShownAtom);
 
@@ -49,7 +51,7 @@ function SideMenu() {
 
       <hr />
 
-      <ExampleList />
+      <ExampleList excludeTags={isDev ? [] : ['experimental']} />
 
       <div className="flex justify-between text-tameplum-800 text-xs">
         <div>&copy; 2024 Software Mansion S.A.</div>

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

@@ -2,7 +2,7 @@ import { examplesByCategory } from '../utils/examples/exampleContent';
 import { exampleCategories } from '../utils/examples/types';
 import { ExampleLink } from './ExampleLink';
 
-function ExampleList() {
+function ExampleList({ excludeTags = [] }: { excludeTags?: string[] }) {
   return (
     <>
       <nav className="flex flex-col flex-1 gap-7 py-4 overflow-y-auto min-w-64">
@@ -11,11 +11,19 @@ function ExampleList() {
         </ExampleLink>
         <hr /> */}
         {exampleCategories.map((category) =>
-          (examplesByCategory[category.key] ?? []).map((example) => (
-            <ExampleLink key={example.key} exampleKey={example.key}>
-              {example.metadata.title}
-            </ExampleLink>
-          )),
+          (examplesByCategory[category.key] ?? []).map((example) => {
+            if (
+              example.metadata.tags?.some((tag) => excludeTags.includes(tag))
+            ) {
+              return null;
+            }
+
+            return (
+              <ExampleLink key={example.key} exampleKey={example.key}>
+                {example.metadata.title}
+              </ExampleLink>
+            );
+          }),
         )}
       </nav>
     </>

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

@@ -29,6 +29,7 @@ type Props = {
 function useExample(
   exampleCode: string,
   setSnackbarText: (text: string | undefined) => void,
+  tags?: string[],
 ) {
   const exampleRef = useRef<ExampleState | null>(null);
   const setExampleControlParams = useSetAtom(exampleControlsAtom);
@@ -38,7 +39,7 @@ function useExample(
     let cancelled = false;
     setSnackbarText(undefined);
 
-    executeExample(exampleCode, createLayout)
+    executeExample(exampleCode, createLayout, tags)
       .then((example) => {
         if (cancelled) {
           // Another instance was started in the meantime.
@@ -67,7 +68,13 @@ function useExample(
       exampleRef.current?.dispose();
       cancelled = true;
     };
-  }, [exampleCode, createLayout, setSnackbarText, setExampleControlParams]);
+  }, [
+    exampleCode,
+    createLayout,
+    setSnackbarText,
+    setExampleControlParams,
+    tags,
+  ]);
 
   return {
     def,
@@ -76,7 +83,7 @@ function useExample(
 }
 
 export function ExampleView({ example, isPlayground = false }: Props) {
-  const { code: initialCode } = example;
+  const { code: initialCode, metadata } = example;
   const [code, setCode] = useState(initialCode);
   const [snackbarText, setSnackbarText] = useState<string | undefined>();
   const setCurrentExample = useSetAtom(currentExampleAtom);
@@ -107,7 +114,7 @@ export function ExampleView({ example, isPlayground = false }: Props) {
     setCodeDebouncer.call(newCode);
   });
 
-  const { def, setRef } = useExample(code, setSnackbarText);
+  const { def, setRef } = useExample(code, setSnackbarText, metadata.tags);
 
   return (
     <>

apps/typegpu-docs/src/content/examples/algorithms/matrix-multiplication.ts

@@ -1,7 +1,8 @@
 /*
 {
   "title": "Matrix Multiplication",
-  "category": "algorithms"
+  "category": "algorithms",
+  "tags": ["experimental"]
 }
 */
 

apps/typegpu-docs/src/content/examples/image-processing/blur.ts

@@ -1,7 +1,8 @@
 /*
 {
   "title": "Image Blur",
-  "category": "image-processing"
+  "category": "image-processing",
+  "tags": ["experimental"]
 }
 */
 

apps/typegpu-docs/src/content/examples/image-processing/camera-thresholding.ts

@@ -1,7 +1,8 @@
 /*
 {
   "title": "Camera Thresholding",
-  "category": "image-processing"
+  "category": "image-processing",
+  "tags": ["experimental"]
 }
 */
 

apps/typegpu-docs/src/content/examples/image-processing/chrome-keying.ts

@@ -1,7 +1,8 @@
 /*
 {
   "title": "Chroma Keying",
-  "category": "image-processing"
+  "category": "image-processing",
+  "tags": ["experimental"]
 }
 */
 

apps/typegpu-docs/src/content/examples/rendering/box-raytracing.ts

@@ -1,7 +1,8 @@
 /*
 {
   "title": "Box Raytracing",
-  "category": "rendering"
+  "category": "rendering",
+  "tags": ["experimental"]
 }
 */
 

apps/typegpu-docs/src/content/examples/simple/gradient-tiles.ts

@@ -1,7 +1,8 @@
 /*
 {
   "title": "Gradient Tiles",
-  "category": "simple"
+  "category": "simple",
+  "tags": ["experimental"]
 }
 */
 

apps/typegpu-docs/src/content/examples/simple/increment-tgsl.ts

@@ -1,7 +1,8 @@
 /*
 {
   "title": "Increment (TGSL)",
-  "category": "simple"
+  "category": "simple",
+  "tags": ["experimental"]
 }
 */
 

apps/typegpu-docs/src/content/examples/simple/increment.ts

@@ -1,7 +1,8 @@
 /*
 {
   "title": "Increment",
-  "category": "simple"
+  "category": "simple",
+  "tags": ["experimental"]
 }
 */
 

apps/typegpu-docs/src/content/examples/simulation/boids.ts

@@ -1,7 +1,8 @@
 /*
 {
   "title": "Boids",
-  "category": "simulation"
+  "category": "simulation",
+  "tags": ["experimental"]
 }
 */
 

apps/typegpu-docs/src/content/examples/simulation/fluid-double-buffering.ts

@@ -1,7 +1,8 @@
 /*
 {
   "title": "Fluid (double-buffering)",
-  "category": "simulation"
+  "category": "simulation",
+  "tags": ["experimental"]
 }
 */
 

apps/typegpu-docs/src/content/examples/simulation/fluid-with-atomics.ts

@@ -1,7 +1,8 @@
 /*
 {
   "title": "Fluid (with atomics)",
-  "category": "simulation"
+  "category": "simulation",
+  "tags": ["experimental"]
 }
 */
 

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

@@ -151,6 +151,7 @@ function tsToJs(code: string): string {
 export async function executeExample(
   exampleCode: string,
   createLayout: () => LayoutInstance,
+  tags?: string[],
 ): Promise<ExampleState> {
   const cleanupCallbacks: (() => unknown)[] = [];
 
@@ -298,6 +299,11 @@ export async function executeExample(
         return await import('typegpu/experimental');
       }
       if (moduleKey === 'typegpu/experimental') {
+        if (!tags?.includes('experimental')) {
+          throw new Error(
+            'Examples not labeled as experimental cannot import experimental modules.',
+          );
+        }
         return await import('typegpu/experimental');
       }
       if (moduleKey === 'typegpu/data') {

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

@@ -4,6 +4,7 @@ export type ExampleMetadata = z.infer<typeof ExampleMetadata>;
 export const ExampleMetadata = z.object({
   title: z.string(),
   category: z.string(),
+  tags: z.array(z.string()).optional(),
 });
 
 export const exampleCategories = [

packages/typegpu/src/index.ts

@@ -9,7 +9,6 @@ export const tgpu = {
   Uniform,
   Storage,
   Vertex,
-
   createBuffer,
   read,
   write,