Reorganize gallery (#11116)

* Reorganize gallery

* GitHub edit links

* Render sidebar during build

* Auto rebuild when sidebar changes

* Yarn dedupe

* Fixes

* Allow just metadata without text

* Show edit text link if metadata defined

* Update build-scripts/gulp/gallery.js

Co-authored-by: Zack Barett <arnett.zackary@gmail.com>

Co-authored-by: Zack Barett <arnett.zackary@gmail.com>

build-scripts/gulp/clean.js

@@ -31,6 +31,6 @@ gulp.task("clean-hassio", () =>
 gulp.task(
   "clean-gallery",
   gulp.parallel("clean-translations", () =>
-    del([paths.gallery_output_root, paths.build_dir])
+    del([paths.gallery_output_root, paths.gallery_build, paths.build_dir])
   )
 );

build-scripts/gulp/gallery.js

@@ -1,8 +1,11 @@
+/* eslint-disable */
 // Run demo develop mode
 const gulp = require("gulp");
 const fs = require("fs");
 const path = require("path");
 const marked = require("marked");
+const glob = require("glob");
+const yaml = require("js-yaml");
 
 const env = require("../env");
 const paths = require("../paths");
@@ -18,7 +21,7 @@ require("./rollup.js");
 
 gulp.task("gather-gallery-demos", async function gatherDemos() {
   const demoDir = path.resolve(paths.gallery_dir, "src/demos");
-  const files = await fs.promises.readdir(demoDir);
+  const files = glob.sync(path.resolve(demoDir, "**/*"));
 
   const galleryBuild = path.resolve(paths.gallery_dir, "build");
   fs.mkdirSync(galleryBuild, { recursive: true });
@@ -28,47 +31,110 @@ gulp.task("gather-gallery-demos", async function gatherDemos() {
   const processed = new Set();
 
   for (const file of files) {
-    let demoId = path.basename(
-      file,
-      file.endsWith(".ts") ? ".ts" : ".markdown"
-    );
+    if (fs.lstatSync(file).isDirectory()) {
+      continue;
+    }
+    demoId = file.substring(demoDir.length + 1, file.lastIndexOf("."));
 
-    // Can be processed if we saw demo or description before.
     if (processed.has(demoId)) {
       continue;
     }
-
     processed.add(demoId);
 
-    const demoFile = path.resolve(demoDir, `${demoId}.ts`);
+    const [category, name] = demoId.split("/", 2);
 
+    const demoFile = path.resolve(demoDir, `${demoId}.ts`);
     const descriptionFile = path.resolve(demoDir, `${demoId}.markdown`);
     const hasDemo = fs.existsSync(demoFile);
-    const hasDescription = fs.existsSync(descriptionFile);
+    let hasDescription = fs.existsSync(descriptionFile);
+    let metadata = {};
     if (hasDescription) {
-      const descriptionContent = fs.readFileSync(descriptionFile, "utf-8");
-      fs.writeFileSync(
-        path.resolve(galleryBuild, `${demoId}-description.ts`),
-        `
-        import {html} from "lit";
-        export default html\`${marked(descriptionContent)}\`
-        `
-      );
+      let descriptionContent = fs.readFileSync(descriptionFile, "utf-8");
+
+      if (descriptionContent.startsWith("---")) {
+        const metadataEnd = descriptionContent.indexOf("---", 3);
+        metadata = yaml.load(descriptionContent.substring(3, metadataEnd));
+        descriptionContent = descriptionContent
+          .substring(metadataEnd + 3)
+          .trim();
+      }
+
+      // If description is just metadata
+      if (descriptionContent === "") {
+        hasDescription = false;
+      } else {
+        fs.mkdirSync(path.resolve(galleryBuild, category), { recursive: true });
+        fs.writeFileSync(
+          path.resolve(galleryBuild, `${demoId}-description.ts`),
+          `
+          import {html} from "lit";
+          export default html\`${marked(descriptionContent)}\`
+          `
+        );
+      }
     }
-    const demoPath = `../src/demos/${demoId}`;
-    const descriptionPath = `./${demoId}-description`;
-    content += `  "${demoId.substring(5)}": {
+    content += `  "${demoId}": {
+      metadata: ${JSON.stringify(metadata)},
       ${
         hasDescription
-          ? `description: () => import("${descriptionPath}").then(m => m.default),`
+          ? `description: () => import("./${demoId}-description").then(m => m.default),`
           : ""
       }
-      ${hasDemo ? `load: () => import("${demoPath}")` : ""}
+      ${hasDemo ? `load: () => import("../src/demos/${demoId}")` : ""}
 
     },\n`;
   }
 
-  content += "};";
+  content += "};\n";
+
+  // Generate sidebar
+  const sidebarPath = path.resolve(paths.gallery_dir, "sidebar.js");
+  // To make watch work during development
+  delete require.cache[sidebarPath];
+  const sidebar = require(sidebarPath);
+
+  const demosToProcess = {};
+  for (const key of processed) {
+    const [category, demo] = key.split("/", 2);
+    if (!(category in demosToProcess)) {
+      demosToProcess[category] = new Set();
+    }
+    demosToProcess[category].add(demo);
+  }
+
+  for (const group of Object.values(sidebar)) {
+    const toProcess = demosToProcess[group.category];
+    delete demosToProcess[group.category];
+
+    if (!toProcess) {
+      console.error("Unknown category", group.category);
+      continue;
+    }
+
+    // Any pre-defined groups will not be sorted.
+    if (group.demos) {
+      for (const demo of group.demos) {
+        if (!toProcess.delete(demo)) {
+          console.error("Found unreferenced demo", demo);
+        }
+      }
+    } else {
+      group.demos = [];
+    }
+    for (const demo of Array.from(toProcess).sort()) {
+      group.demos.push(demo);
+    }
+  }
+
+  for (const [category, demos] of Object.entries(demosToProcess)) {
+    sidebar.push({
+      category,
+      header: category,
+      demos: Array.from(demos),
+    });
+  }
+
+  content += `export const SIDEBAR = ${JSON.stringify(sidebar, null, 2)};\n`;
 
   fs.writeFileSync(
     path.resolve(galleryBuild, "import-demos.ts"),
@@ -99,7 +165,10 @@ gulp.task(
         : "webpack-dev-server-gallery",
       async function watchMarkdownFiles() {
         gulp.watch(
-          path.resolve(paths.gallery_dir, "src/demos/*.markdown"),
+          [
+            path.resolve(paths.gallery_dir, "src/demos/**/*.markdown"),
+            path.resolve(paths.gallery_dir, "sidebar.js"),
+          ],
           gulp.series("gather-gallery-demos")
         );
       }