Sandcastle build config updates

.github/workflows/deploy.yml

@@ -43,7 +43,7 @@ jobs:
       - name: build apps
         run: npm run build-apps
       - name: build sandcastle v2
-        run: npm run build-ci -w packages/sandcastle -- -l warn
+        run: npm run build-app -w packages/sandcastle -- -l warn
       - uses: ./.github/actions/verify-package
       - name: deploy to s3
         if: ${{ env.AWS_ACCESS_KEY_ID != '' }}

gulpfile.js

@@ -31,6 +31,11 @@ import {
   createJsHintOptions,
   defaultESBuildOptions,
 } from "./scripts/build.js";
+import { fileURLToPath } from "url";
+import {
+  buildStatic,
+  createSandcastleConfig,
+} from "./packages/sandcastle/scripts/buildStatic.js";
 
 // Determines the scope of the workspace packages. If the scope is set to cesium, the workspaces should be @cesium/engine.
 // This should match the scope of the dependencies of the root level package.json.
@@ -1229,13 +1234,6 @@ function generateTypeScriptDefinitions(
       "raiseEvent(...arguments: Parameters<Listener>): void;",
     );
 
-  // Wrap the source to actually be inside of a declared cesium module
-  // and add any workaround and private utility types.
-  source = `declare module "@${scope}/${workspaceName}" {
-${source}
-}
-`;
-
   if (importModules) {
     let imports = "";
     Object.keys(importModules).forEach((workspace) => {
@@ -1249,6 +1247,13 @@ ${source}
     source = imports + source;
   }
 
+  // Wrap the source to actually be inside of a declared cesium module
+  // and add any workaround and private utility types.
+  source = `declare module "@${scope}/${workspaceName}" {
+${source}
+}
+`;
+
   // Write the final source file back out
   writeFileSync(definitionsPath, source);
 
@@ -1741,6 +1746,31 @@ async function buildSandcastle() {
   return Promise.all(streams.map((s) => finished(s)));
 }
 
+// TODO: clean up
+export async function buildNewSandcastle() {
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const newConfig = createSandcastleConfig({
+    outDir: join(__dirname, "./Apps/Sandcastle2"),
+    viteBase: "/Apps/Sandcastle2",
+    cesiumBaseUrl: "/Build/CesiumUnminified",
+    imports: {
+      cesium: {
+        path: "/Source/Cesium.js",
+        typesPath: "/Source/Cesium.d.ts",
+      },
+      "@cesium/engine": {
+        path: "/packages/engine/Build/Unminified/index.js",
+        typesPath: "/packages/engine/index.d.ts",
+      },
+      "@cesium/widgets": {
+        path: "/packages/widgets/Build/Unminified/index.js",
+        typesPath: "/packages/widgets/index.d.ts",
+      },
+    },
+  });
+  await buildStatic(newConfig);
+}
+
 async function buildCesiumViewer() {
   const cesiumViewerOutputDirectory = isProduction
     ? "Build/CesiumViewer"

package.json

@@ -115,7 +115,7 @@
     "build-ts": "gulp buildTs",
     "build-third-party": "gulp buildThirdParty",
     "build-apps": "gulp buildApps",
-    "build-sandcastle": "npm run build-app --workspace packages/sandcastle",
+    "build-sandcastle": "gulp buildNewSandcastle",
     "clean": "gulp clean",
     "cloc": "gulp cloc",
     "coverage": "gulp coverage",
@@ -171,4 +171,4 @@
       }
     }
   }
-}
+}

packages/sandcastle/README.md

@@ -7,7 +7,7 @@ This package is the application for Sandcastle.
 - `npm run dev`: run the development server
 - `npm run build`: alias for `npm run build-app`
 - `npm run build-app`: build to static files in `/Apps/Sandcastle2` for hosting/access from the root cesium dev server
-- `npm run build-ci`: build to static files in `/Apps/Sandcastle2` and configure paths as needed for CI deployment
+  - If the env variable `BASE_URL` is set it will be prefixed on all required paths in the application. This is useful for building to a "nested" url like we do in CI
 
 Linting and style is managed under the project root's scripts.
 

packages/sandcastle/gallery/cesium-inspector/sandcastle.yaml

@@ -5,3 +5,4 @@ labels:
   - Development
   - Entities
 thumbnail: thumbnail.jpg
+development: true

packages/sandcastle/gallery/fog/sandcastle.yaml

@@ -4,3 +4,4 @@ description: Control fog parameters.
 labels:
   - Development
 thumbnail: thumbnail.jpg
+development: true

packages/sandcastle/package.json

@@ -10,7 +10,6 @@
     "dev": "npm run build-gallery && vite --config vite.config.dev.ts",
     "build": "npm run build-app",
     "build-app": "tsc -b && npm run build-gallery && vite build --config vite.config.app.ts",
-    "build-ci": "tsc -b && npm run build-gallery && vite build --config vite.config.ci.ts",
     "build-prod": "tsc -b && npm run build-gallery && vite build --config vite.config.prod.ts",
     "build-gallery": "node scripts/buildGallery.js"
   },

packages/sandcastle/sandcastle.config.js

@@ -1,7 +1,9 @@
+import process from "process";
+
 const config = {
   root: ".",
   sourceUrl: "https://github.com/CesiumGS/cesium/blob/main/packages/sandcastle",
-  publicDir: "./public",
+  publicDirectory: "./public",
   gallery: {
     files: ["gallery"],
     searchOptions: {
@@ -19,7 +21,7 @@ const config = {
       labels: [],
       development: false,
     },
-    includeDevelopment: true,
+    includeDevelopment: !process.env.PROD,
   },
 };
 

packages/sandcastle/scripts/buildGallery.js

@@ -174,7 +174,11 @@ export async function buildGalleryList(options = {}) {
     if (
       check(!/^[a-zA-Z0-9-.]+$/.test(slug), `"${slug}" is not a valid slug`) ||
       check(!title, `${slug} - Missing title`) ||
-      check(!description, `${slug} - Missing description`)
+      check(!description, `${slug} - Missing description`) ||
+      check(
+        !development && labels.includes("Development"),
+        `${slug} has Development label but not marked as development sandcastle`,
+      )
     ) {
       continue;
     }
@@ -300,7 +304,7 @@ if (import.meta.url.endsWith(`${pathToFileURL(process.argv[1])}`)) {
 
   try {
     const config = await import(pathToFileURL(configPath).href);
-    const { root, publicDir, gallery, sourceUrl } = config.default;
+    const { root, publicDirectory, gallery, sourceUrl } = config.default;
 
     // Paths are specified relative to the config file
     const configDir = dirname(configPath);
@@ -316,7 +320,7 @@ if (import.meta.url.endsWith(`${pathToFileURL(process.argv[1])}`)) {
 
     buildGalleryOptions = {
       rootDirectory: configRoot,
-      publicDirectory: publicDir,
+      publicDirectory: publicDirectory,
       galleryFiles: files,
       sourceUrl,
       defaultThumbnail,

packages/sandcastle/scripts/buildStatic.js

@@ -0,0 +1,141 @@
+import { build, defineConfig } from "vite";
+import baseConfig from "../vite.config.js";
+import { fileURLToPath } from "url";
+import { viteStaticCopy } from "vite-plugin-static-copy";
+import { dirname, join } from "path";
+import { cesiumPathReplace, insertImportMap } from "../vite-plugins.js";
+import typescriptCompile from "./typescriptCompile.js";
+
+/** @import { UserConfig } from 'vite' */
+
+/**
+ * @typedef {Object} ImportObject
+ * @property {string} path The path to use for the import map. ie the path the app can expect to find this at
+ * @property {string} typesPath The path to use for intellisense types in monaco
+ */
+
+/**
+ * @typedef {Object<string, ImportObject>} ImportList
+ */
+
+/**
+ * Check if the given key is in the imports list and throw an error if not
+ * @param {ImportList} imports
+ * @param {string} name
+ */
+function checkForImport(imports, name) {
+  if (!imports[name]) {
+    throw new Error(`Missing import for ${name}`);
+  }
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Create the Vite configuration for building Sandcastle.
+ * Set where it should build to and the base path for vite and CesiumJS files.
+ *
+ * Most importantly specify the paths the app can find the library imports.
+ *
+ * If you are copying files to the built directory ensure the source files exist BEFORE attempting to build Sandcastle
+ *
+ * @param {object} options
+ * @param {string} options.outDir Path to build files into
+ * @param {string} options.viteBase Base path for files/routes
+ * @param {string} options.cesiumBaseUrl Base path for CesiumJS. This should include the CesiumJS assets and workers etc.
+ * @param {string} [options.commitSha] Optional commit hash to display in the top right of the application
+ * @param {ImportList} options.imports Set of imports to add to the import map for the iframe and standalone html pages. These paths should match the URL where it can be accessed within the current environment.
+ * @param {{src: string, dest: string}[]} [options.copyExtraFiles] Extra paths passed to viteStaticCopy. Use this to consolidate files for a singular static deployment (ie during production). Source paths should be absolute, dest paths should be relative to the page root. It is up to you to ensure these files exist BEFORE building sandcastle.
+ */
+export function createSandcastleConfig({
+  outDir,
+  viteBase,
+  cesiumBaseUrl,
+  commitSha,
+  imports,
+  copyExtraFiles = [],
+}) {
+  /** @type {UserConfig} */
+  const config = { ...baseConfig };
+
+  config.base = viteBase;
+
+  config.build = {
+    ...config.build,
+    outDir: outDir,
+  };
+
+  const copyPlugin = viteStaticCopy({
+    targets: [
+      { src: "templates/Sandcastle.(d.ts|js)", dest: "templates" },
+      ...copyExtraFiles,
+    ],
+  });
+
+  checkForImport(imports, "cesium");
+  checkForImport(imports, "@cesium/engine");
+  checkForImport(imports, "@cesium/widgets");
+  if (imports["Sandcastle"]) {
+    throw new Error(
+      "Don't specify the Sandcastle import this is taken care of internally",
+    );
+  }
+
+  /** @type {Object<string, string>} */
+  const importMap = {
+    Sandcastle: `${viteBase}/templates/Sandcastle.js`,
+  };
+  /** @type {Object<string, string>} */
+  const typePaths = {
+    Sandcastle: "templates/Sandcastle.d.ts",
+  };
+  for (const [key, value] of Object.entries(imports)) {
+    importMap[key] = value.path;
+    typePaths[key] = value.typesPath;
+  }
+
+  config.define = {
+    ...config.define,
+    __VITE_TYPE_IMPORT_PATHS__: JSON.stringify(typePaths),
+    __COMMIT_SHA__: JSON.stringify(commitSha ?? undefined),
+  };
+
+  const plugins = config.plugins ?? [];
+  config.plugins = [
+    ...plugins,
+    copyPlugin,
+    cesiumPathReplace(cesiumBaseUrl),
+    insertImportMap(importMap, ["bucket.html", "standalone.html"]),
+  ];
+
+  return defineConfig(config);
+}
+
+/**
+ * Build Sandcastle out to a specified location as static files.
+ * The config should be generated with the <code>createSandcastleConfig</code> function.
+ *
+ * The build will only set up the paths for "external" resources from the app.
+ * If you are copying files to the built directory ensure the source files exist BEFORE attempting to build Sandcastle
+ *
+ * @param {UserConfig} config
+ */
+export async function buildStatic(config) {
+  // We have to do the compile for the Sandcastle API outside of the vite build
+  // because we need to reference the js file and types directly from the app
+  // and we don't want them bundled with the rest of the code
+  const exitCode = typescriptCompile(
+    join(__dirname, "../templates/tsconfig.lib.json"),
+  );
+
+  if (exitCode === 0) {
+    console.log(`Sandcastle typescript build complete`);
+  } else {
+    throw new Error("Sandcastle typescript build failed");
+  }
+
+  await build({
+    ...config,
+    root: join(__dirname, "../"),
+  });
+}