feat(docs): allow all demos to be created in stackblitz

I'm not supporting codesandbox at this time since it doesn't really
support sass and the define API doesn't support devboxes.

Author: mlaursen

apps/docs/package.json

@@ -8,6 +8,7 @@
     "run-script": "tsx --tsconfig scripts/tsconfig.json",
     "create-env": "pnpm run run-script scripts/createEnv.ts",
     "create-scss-lookup": "pnpm run run-script scripts/createScssLookup.ts",
+    "create-stackblitz-template": "pnpm run run-script scripts/createStackBlitzTemplate.ts",
     "typecheck-src": "tsc --noEmit",
     "typecheck-scripts": "tsc --noEmit -P scripts/tsconfig.json",
     "typecheck": "npm-run-all typecheck-src typecheck-scripts",
@@ -21,7 +22,7 @@
     "watch-demos": "pnpm run run-script scripts/watchDemos.ts",
     "watch-scss-lookup": "pnpm create-scss-lookup -- --watch",
     "generator-dev": "nodemon --config scripts/nodemon.docs-generator.json",
-    "build-env": "npm-run-all --parallel create-env sassdoc create-scss-lookup",
+    "build-env": "npm-run-all --parallel create-env sassdoc create-scss-lookup create-stackblitz-template",
     "build-typedoc": "pnpm run run-script scripts/typedoc.ts",
     "next-dev": "next dev",
     "next-build": "next build",

apps/docs/scripts/constants.ts

@@ -4,6 +4,8 @@ import { join } from "node:path";
 export const GENERATED_FILE_BANNER =
   "// THIS FILE WAS GENERATED BY A SCRIPT AND SHOULD NOT BE UPDATED MANUALLY";
 
+const aliased = (name: string): string => name.replace(/^.+src\//, "@/");
+
 export const PROJECT_ROOT = getProjectRootDir();
 export const CORE_ROOT = join(PROJECT_ROOT, "packages", "core");
 export const CORE_SRC = join(CORE_ROOT, "src");
@@ -15,7 +17,7 @@ export const GENERATED_DIR = join(
   "generated"
 );
 export const GENERATED_SASSDOC_FILE = join(GENERATED_DIR, "sassdoc.ts");
-export const ALIASED_SASSDOC_FILE = GENERATED_SASSDOC_FILE.replace(
-  /^.+src\//,
-  "@/"
-);
+export const ALIASED_SASSDOC_FILE = aliased(GENERATED_SASSDOC_FILE);
+
+export const GENERATED_STACKBLITZ_FILE = join(GENERATED_DIR, "stackblitz.ts");
+export const ALIASED_STACKBLITZ_FILE = aliased(GENERATED_SASSDOC_FILE);

apps/docs/scripts/createStackBlitzTemplate.ts

@@ -0,0 +1,97 @@
+import { getProjectRootDir } from "docs-generator/utils/getProjectRootDir";
+import { log } from "docs-generator/utils/log";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { format } from "prettier";
+
+import packageJson from "../package.json" with { type: "json" };
+import {
+  GENERATED_FILE_BANNER,
+  GENERATED_STACKBLITZ_FILE,
+} from "./constants.js";
+import { ensureGeneratedDir } from "./ensureGeneratedDir.js";
+
+function getAllFiles(dir: string): readonly string[] {
+  const files: string[] = [];
+  const dirFiles = readdirSync(dir);
+  dirFiles.forEach((file) => {
+    if (
+      /node_modules|(\.git$)|RootLayout|MainNavigation|README|CHANGELOG|(\.(ico|png))/.test(
+        file
+      )
+    ) {
+      return;
+    }
+
+    const fullPath = join(dir, file);
+    if (statSync(fullPath).isDirectory()) {
+      files.push(...getAllFiles(fullPath));
+    } else {
+      files.push(fullPath);
+    }
+  });
+
+  return files;
+}
+
+interface TemplateHiddenInputProps {
+  name: string;
+  value: string;
+}
+
+function toTemplateHiddenInputProps(
+  fullFilePath: string
+): TemplateHiddenInputProps {
+  const srcPath = fullFilePath.replace(/^.+vite-(t|j)s\//, "");
+  const name = basename(srcPath);
+
+  let contents = readFileSync(fullFilePath, "utf8");
+  if (name === "package.json") {
+    const parsed = JSON.parse(contents);
+    // sass-embedded doesn't work here for some reason
+    parsed.devDependencies.sass = parsed.devDependencies["sass-embedded"];
+    delete parsed.devDependencies["sass-embedded"];
+
+    contents = JSON.stringify(parsed, null, 2);
+  } else if (name === "index.html") {
+    contents = contents.replace(
+      /id="root"/,
+      `id="root" class="{{CLASS_NAME}}"`
+    );
+  }
+
+  return {
+    name: `project[files][${srcPath}]`,
+    value: contents,
+  };
+}
+
+async function run(): Promise<void> {
+  await ensureGeneratedDir();
+
+  const examplesRoot = join(getProjectRootDir(), "examples");
+  const typescriptFiles = getAllFiles(join(examplesRoot, "vite-ts"));
+  const javascriptFiles = getAllFiles(join(examplesRoot, "vite-js"));
+
+  const contents = `${GENERATED_FILE_BANNER}
+
+export const JS_STACKBLITZ_TEMPLATE = ${JSON.stringify(javascriptFiles.map((file) => toTemplateHiddenInputProps(file)))}
+export const TS_STACKBLITZ_TEMPLATE = ${JSON.stringify(typescriptFiles.map((file) => toTemplateHiddenInputProps(file)))}
+
+export const STACKBLITZ_DEPENDENCIES: Record<string, string> = ${JSON.stringify(
+    {
+      ...packageJson.dependencies,
+      ...packageJson.devDependencies,
+    }
+  )}
+`;
+
+  await writeFile(
+    GENERATED_STACKBLITZ_FILE,
+    await format(contents, { filepath: GENERATED_STACKBLITZ_FILE }),
+    "utf8"
+  );
+}
+
+await log(run(), "", `Created ${GENERATED_STACKBLITZ_FILE}`);

apps/docs/scripts/ensureGeneratedDir.ts

@@ -0,0 +1,10 @@
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+
+import { GENERATED_DIR } from "./constants.js";
+
+export async function ensureGeneratedDir(): Promise<void> {
+  if (!existsSync(GENERATED_DIR)) {
+    await mkdir(GENERATED_DIR, { recursive: true });
+  }
+}

apps/docs/scripts/sassdoc.ts

@@ -1,17 +1,16 @@
 import { log } from "docs-generator/utils/log";
-import { existsSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
+import { writeFile } from "node:fs/promises";
 import { format } from "prettier";
 import { type GeneratedSassDocWithOrder, generate } from "sassdoc-generator";
 import { type FormattedSassDocItem } from "sassdoc-generator/types";
 
 import {
   ALIASED_SASSDOC_FILE,
   CORE_SRC,
-  GENERATED_DIR,
   GENERATED_FILE_BANNER,
   GENERATED_SASSDOC_FILE,
 } from "./constants.js";
+import { ensureGeneratedDir } from "./ensureGeneratedDir.js";
 
 function stringify(
   map: ReadonlyMap<string, FormattedSassDocItem>,
@@ -53,10 +52,7 @@ export const SASSDOC_VARIABLES: Record<string, FormattedVariableItem | undefined
 }
 
 async function run(): Promise<void> {
-  if (!existsSync(GENERATED_DIR)) {
-    await mkdir(GENERATED_DIR, { recursive: true });
-  }
-
+  await ensureGeneratedDir();
   await createSassDocFile(await generate({ src: CORE_SRC }));
 }
 

apps/docs/src/app/(main)/(markdown)/(demos)/hooks/use-file-upload/page.mdx

@@ -16,7 +16,7 @@ uploaded to a server.
 This example will show how to handle simple validation and preview uploaded
 files. Only the `Demo` files are editable.
 
-```demo source="./FileUploadExample.tsx" readOnlyImports={["@/components/FilePreview/FilePreviewCard.jsx", "@/components/FilePreview/SimpleFilePreview.tsx", "@/components/FilePreview/FilePreviewCard.module.scss", "@/components/FileUploadErrorModal/FileUploadErrorModal.jsx", "@/components/FileUploadErrorModal/ErrorRenderer.jsx"]}
+```demo source="./FileUploadExample.tsx" readOnlyImports={["@/components/FilePreview/FilePreviewCard.jsx", "@/components/FilePreview/FilePreviewCard.module.scss", "@/components/FilePreview/SimpleFilePreview.jsx", "@/components/FileUploadErrorModal/FileUploadErrorModal.jsx", "@/components/FileUploadErrorModal/ErrorRenderer.jsx", "@/components/FileUploadErrorModal/ErrorHeader.jsx"]}
 
 ```
 
@@ -30,7 +30,7 @@ upload files to the server using this hook.
 > !Success! This example also showcases some other UI that can be rendered by
 > utilizing the data returned by this hook.
 
-```demo source="./ServerUploadExample.tsx" readOnlyImports={["@/components/FilePreview/FilePreviewCard.jsx", "@/components/FilePreview/SimpleFilePreview.tsx", "@/components/FileUploadErrorModal/FileUploadErrorModal.jsx", "@/components/FileUploadErrorModal/ErrorRenderer.jsx"]}
+```demo source="./ServerUploadExample.tsx" readOnlyImports={["@/components/FileUploadErrorModal/FileUploadErrorModal.jsx", "@/components/FileUploadErrorModal/ErrorRenderer.jsx", "@/components/FileUploadErrorModal/ErrorHeader.jsx"]}
 
 ```
 

apps/docs/src/components/DemoCode/DemoCodeEditor.tsx

@@ -21,7 +21,7 @@ import { Slide } from "@react-md/core/transition/Slide";
 import { useToggle } from "@react-md/core/useToggle";
 import EditOffIcon from "@react-md/material-icons/EditOffIcon";
 import RefreshOutlinedIcon from "@react-md/material-icons/RefreshOutlinedIcon";
-import { type ReactElement, useMemo, useRef } from "react";
+import { type ReactElement, type ReactNode, useMemo, useRef } from "react";
 
 import { GithubLink } from "../GithubLink.jsx";
 import { ConfigureTypescriptEnabled } from "../MainLayout/ConfigureTypescriptEnabled.jsx";
@@ -44,6 +44,7 @@ export interface DemoCodeEditorProps extends PreviewContainerOptions {
   startOnScss?: boolean;
   readOnlyFiles?: readonly ReactElement[];
   readOnlyFileNames?: readonly string[];
+  beforeSourceLinkChildren?: ReactNode;
 }
 
 export function DemoCodeEditor(props: DemoCodeEditorProps): ReactElement {
@@ -60,6 +61,7 @@ export function DemoCodeEditor(props: DemoCodeEditorProps): ReactElement {
     scssCodeFile,
     forceDarkMode,
     disablePadding,
+    beforeSourceLinkChildren,
     readOnlyFiles = [],
     readOnlyFileNames = [],
   } = props;
@@ -125,6 +127,7 @@ export function DemoCodeEditor(props: DemoCodeEditorProps): ReactElement {
             </Chip>
           )}
           <Box className={styles.end} disablePadding disableWrap>
+            {beforeSourceLinkChildren}
             <GithubLink
               file={source}
               iconSize="small"

apps/docs/src/components/DemoCode/ReadOnlyFile.tsx

@@ -0,0 +1,25 @@
+import { type ReadonlyCodeFile } from "@react-md/code/types";
+import { type ReactElement } from "react";
+
+import { MarkdownCode } from "../MarkdownCode.jsx";
+import { TypescriptCodeBlock } from "../TypescriptCodeBlock.jsx";
+
+export interface ReadOnlyFileProps {
+  file: ReadonlyCodeFile;
+}
+
+export function ReadOnlyFile(props: ReadOnlyFileProps): ReactElement {
+  const { file } = props;
+  if ("compiled" in file) {
+    return (
+      <TypescriptCodeBlock
+        isTsx={file.name.endsWith(".tsx")}
+        tsCode={file.code}
+        jsCode={file.compiled}
+        disableAppBar
+      />
+    );
+  }
+
+  return <MarkdownCode language={file.lang}>{file.code}</MarkdownCode>;
+}

apps/docs/src/components/FileUploadErrorModal/ErrorHeader.tsx

@@ -13,7 +13,7 @@ interface ErrorHeaderProps {
   error: TooManyFilesError | FileSizeError | FileExtensionError;
 }
 
-export default function ErrorHeader({ error }: ErrorHeaderProps): ReactElement {
+export function ErrorHeader({ error }: ErrorHeaderProps): ReactElement {
   if (isFileSizeError(error)) {
     const { type } = error;
     const limit = filesize(error.limit);

apps/docs/src/components/FileUploadErrorModal/ErrorRenderer.tsx

@@ -7,7 +7,7 @@ import { Typography } from "@react-md/core/typography/Typography";
 import { filesize } from "filesize";
 import { Fragment, type ReactElement } from "react";
 
-import ErrorHeader from "./ErrorHeader.jsx";
+import { ErrorHeader } from "./ErrorHeader.jsx";
 
 export interface ErrorRendererProps {
   error: FileValidationError<never>;