Merge pull request #15 from Workday/make-examples-downloadable

Make examples downloadable

Author: Ekwuno

.gitignore

@@ -4,6 +4,7 @@ node_modules/
 # Site build output
 site/dist/
 site/.astro/
+site/public/downloads/
 
 # Environment files (never commit credentials)
 .env

CONTRIBUTING.md

@@ -35,7 +35,7 @@ Thanks for helping build the open home for Workday Build examples. Adding an exa
 
    Each creates `examples/your-example-name/` with a prefilled `example.json` and README skeleton. (You can also copy `examples/_template/` by hand.)
 
-3. **Drop your artifact in.** Whatever it is: Extend app source (exported with Local Disk Sync, the WDCLI, or the ZIP download), orchestration definitions, an agent skill as markdown, diagrams. The folder must be self-contained.
+3. **Drop your artifact in.** Whatever it is: Extend app source (exported with Local Disk Sync, the WDCLI, or the ZIP download), orchestration definitions, an agent skill as markdown, diagrams. The folder must be self-contained. Once merged, the gallery serves the folder as a zip download automatically; nothing extra to do.
 4. **Fill in the two files.** `example.json` needs a title, a description, and a type; everything else is optional. The README needs four short sections: What it is, What's inside, How to use it, and Before you deploy (everything a reader must change for their own tenant, such as app reference ids, base URLs, WIDs, or dates).
 5. **Validate.** From the repository root:
 

README.md

@@ -55,6 +55,8 @@ hub.config.json          Repo URLs and the approved type, component, and product
 
 ## Use an example
 
+Every example can be downloaded on its own from the [gallery](https://workday.github.io/WorkdayDeveloperProgram/): each card and example page has a **Download zip** button, so there is no need to clone the whole repository. The zip includes a `SOURCE.md` that records the commit it was built from and how to send changes back. To work with git instead:
+
 ```bash
 git clone https://github.com/Workday/WorkdayDeveloperProgram
 cd WorkdayDeveloperProgram

site/README.md

@@ -0,0 +1,21 @@
+# Gallery site
+
+The optional gallery for the Workday Examples Hub, built with Astro and Tailwind and deployed to GitHub Pages by `.github/workflows/deploy-gallery.yml`.
+
+```bash
+npm install
+npm run dev      # local preview
+npm run build    # static output in dist/
+```
+
+## How it reads the examples
+
+`src/lib/examples.js` globs every `catalog/*/example.json` and `examples/*/example.json` at build time. There is no manifest to regenerate; a folder shows up as soon as it exists.
+
+## Per-example downloads
+
+`scripts/build-zips.mjs` runs before `dev` and `build` (the `predev` and `prebuild` scripts) and zips every example folder into `public/downloads/<section>/<id>.zip`. Astro copies `public/` into `dist/`, so the same URLs work locally and on Pages.
+
+- Each zip wraps the folder in `<id>/` with `appManifest.json` at its root, includes `README.md`, and leaves out `example.json` (hub metadata only).
+- Each zip also gets a generated `SOURCE.md` with the repository, folder, commit, a sparse checkout command, and how to open a pull request. The text lives in `src/lib/gitTrace.js`, shared with the example page.
+- `public/downloads/` is generated output and is gitignored. Do not commit it.

site/package-lock.json

@@ -5,7 +5,9 @@
   "description": "Optional gallery site for the Workday Use Case Hub. Built with Astro and Tailwind.",
   "type": "module",
   "scripts": {
+    "predev": "node scripts/build-zips.mjs",
     "dev": "astro dev",
+    "prebuild": "node scripts/build-zips.mjs",
     "build": "astro build",
     "preview": "astro preview"
   },
@@ -14,5 +16,8 @@
     "@tailwindcss/vite": "^4.1.0",
     "astro": "^5.0.0",
     "tailwindcss": "^4.1.0"
+  },
+  "devDependencies": {
+    "fflate": "^0.8.3"
   }
 }

site/package.json

@@ -0,0 +1,76 @@
+// Zips every example folder into public/downloads/<section>/<id>.zip so the
+// gallery can offer per-example downloads without anyone cloning the repo.
+// Runs before `astro dev` and `astro build` (see package.json). Output is
+// gitignored. Each zip gets a SOURCE.md that points back to the repository
+// and the commit it was built from.
+
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { zipSync } from "fflate";
+import { sourceMarkdown } from "../src/lib/gitTrace.js";
+
+const siteDir = fileURLToPath(new URL("..", import.meta.url));
+const repoRoot = join(siteDir, "..");
+const outRoot = join(siteDir, "public", "downloads");
+const hub = JSON.parse(readFileSync(join(repoRoot, "hub.config.json"), "utf8"));
+
+// Hub metadata and OS noise stay out of the zip; everything else ships.
+const SKIP = new Set([".DS_Store", ".gitkeep", "example.json", "node_modules", ".git"]);
+// Fixed timestamp so building the same commit twice yields identical bytes.
+const MTIME = new Date("2000-01-01T00:00:00Z");
+
+const sha = process.env.GITHUB_SHA || git("rev-parse HEAD") || "unknown";
+// Commit date rather than wall clock, so the same commit always builds the same bytes.
+const date = (git("log -1 --format=%cI") || new Date().toISOString()).slice(0, 10);
+
+function git(args) {
+  try {
+    return execSync(`git ${args}`, { cwd: repoRoot, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+  } catch {
+    return "";
+  }
+}
+
+function walk(dir) {
+  const out = [];
+  for (const name of readdirSync(dir).sort()) {
+    if (SKIP.has(name)) continue;
+    const abs = join(dir, name);
+    if (statSync(abs).isDirectory()) out.push(...walk(abs));
+    else out.push(abs);
+  }
+  return out;
+}
+
+// Same folder rules as src/lib/examples.js: skip _template, need example.json.
+function exampleDirs(section) {
+  const base = join(repoRoot, section);
+  if (!existsSync(base)) return [];
+  return readdirSync(base)
+    .sort()
+    .filter((id) => !id.startsWith("_") && !id.startsWith("."))
+    .filter((id) => statSync(join(base, id)).isDirectory())
+    .filter((id) => existsSync(join(base, id, "example.json")))
+    .map((id) => ({ id, path: `${section}/${id}`, abs: join(base, id), section }));
+}
+
+rmSync(outRoot, { recursive: true, force: true });
+
+let count = 0;
+for (const section of ["catalog", "examples"]) {
+  for (const example of exampleDirs(section)) {
+    const files = {};
+    for (const abs of walk(example.abs)) {
+      const rel = relative(example.abs, abs).split(sep).join("/");
+      files[`${example.id}/${rel}`] = [readFileSync(abs), { mtime: MTIME }];
+    }
+    files[`${example.id}/SOURCE.md`] = [Buffer.from(sourceMarkdown(example, hub, { sha, date })), { mtime: MTIME }];
+    mkdirSync(join(outRoot, section), { recursive: true });
+    writeFileSync(join(outRoot, section, `${example.id}.zip`), zipSync(files, { level: 6 }));
+    count++;
+  }
+}
+
+console.log(`build-zips: wrote ${count} zip(s) to ${relative(repoRoot, outRoot)} (commit ${sha.slice(0, 7)})`);

site/scripts/build-zips.mjs

@@ -1,6 +1,6 @@
 ---
 import TypeIcon from "./TypeIcon.astro";
-import { withBase, sourceLabel } from "../lib/examples.js";
+import { withBase, sourceLabel, downloadUrl, downloadName } from "../lib/examples.js";
 
 const { example } = Astro.props;
 const detailUrl = withBase(`${example.path}/`);
@@ -10,9 +10,10 @@ const searchText = [example.title, example.description, example.id, example.type
   .join(" ")
   .toLowerCase();
 ---
-<a
-  href={detailUrl}
-  class="example-card group flex flex-col gap-3 rounded-xl border border-neutral-200 bg-white p-5 transition-colors hover:border-neutral-400 dark:border-neutral-800 dark:bg-neutral-950 dark:hover:border-neutral-500"
+{/* The title link is stretched over the whole card (after:inset-0), so the
+    card stays one click target while the download link sits above it. */}
+<div
+  class="example-card group relative flex flex-col gap-3 rounded-xl border border-neutral-200 bg-white p-5 transition-colors hover:border-neutral-400 focus-within:border-neutral-400 dark:border-neutral-800 dark:bg-neutral-950 dark:hover:border-neutral-500 dark:focus-within:border-neutral-500"
   data-section={example.section}
   data-type={example.type}
   data-components={example.components.join("|")}
@@ -22,27 +23,43 @@ const searchText = [example.title, example.description, example.id, example.type
 >
   <div class="flex items-center justify-between">
     <TypeIcon type={example.type} />
-    {badge === "Workday" ? (
-      <span class="inline-flex items-center gap-1.5 rounded-full bg-wd-blue/10 px-2.5 py-1 text-xs font-semibold text-wd-blue">
-        <svg viewBox="0 0 24 24" width="13" height="13" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-          <circle cx="12" cy="12" r="9"></circle>
-          <path d="m9 12 2 2 4-4"></path>
+    <div class="flex items-center gap-2">
+      {badge === "Workday" ? (
+        <span class="inline-flex items-center gap-1.5 rounded-full bg-wd-blue/10 px-2.5 py-1 text-xs font-semibold text-wd-blue">
+          <svg viewBox="0 0 24 24" width="13" height="13" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <circle cx="12" cy="12" r="9"></circle>
+            <path d="m9 12 2 2 4-4"></path>
+          </svg>
+          Workday
+        </span>
+      ) : (
+        <span class="inline-flex items-center gap-1.5 rounded-full border border-neutral-200 px-2.5 py-1 text-xs font-medium text-neutral-500 dark:border-neutral-800 dark:text-neutral-400">
+          <svg viewBox="0 0 24 24" width="13" height="13" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"></path>
+            <circle cx="9" cy="7" r="4"></circle>
+            <path d="M23 21v-2a4 4 0 0 0-3-3.87"></path>
+            <path d="M16 3.13a4 4 0 0 1 0 7.75"></path>
+          </svg>
+          Community
+        </span>
+      )}
+      <a
+        href={downloadUrl(example)}
+        download={downloadName(example)}
+        title="Download zip"
+        aria-label={`Download ${example.title} as a zip`}
+        class="relative z-10 flex h-7 w-7 items-center justify-center rounded-md text-neutral-400 transition-colors hover:bg-neutral-100 hover:text-neutral-900 dark:hover:bg-neutral-900 dark:hover:text-neutral-100"
+      >
+        <svg viewBox="0 0 24 24" width="15" height="15" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M12 3v12m0 0 4-4m-4 4-4-4"></path>
+          <path d="M4 17v2a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-2"></path>
         </svg>
-        Workday
-      </span>
-    ) : (
-      <span class="inline-flex items-center gap-1.5 rounded-full border border-neutral-200 px-2.5 py-1 text-xs font-medium text-neutral-500 dark:border-neutral-800 dark:text-neutral-400">
-        <svg viewBox="0 0 24 24" width="13" height="13" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-          <path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"></path>
-          <circle cx="9" cy="7" r="4"></circle>
-          <path d="M23 21v-2a4 4 0 0 0-3-3.87"></path>
-          <path d="M16 3.13a4 4 0 0 1 0 7.75"></path>
-        </svg>
-        Community
-      </span>
-    )}
+      </a>
+    </div>
   </div>
-  <h2 class="text-base font-semibold tracking-tight">{example.title}</h2>
+  <h2 class="text-base font-semibold tracking-tight">
+    <a href={detailUrl} class="after:absolute after:inset-0 after:content-[''] focus:outline-none">{example.title}</a>
+  </h2>
   <p class="flex-1 text-sm leading-relaxed text-neutral-500 dark:text-neutral-400">{example.description}</p>
   <div class="flex flex-wrap gap-1.5">
     {tags.map((tag) => (
@@ -51,4 +68,4 @@ const searchText = [example.title, example.description, example.id, example.type
       </span>
     ))}
   </div>
-</a>
+</div>

site/src/components/Card.astro

@@ -2,7 +2,7 @@
 import "../styles/global.css";
 import Header from "./Header.astro";
 import Footer from "./Footer.astro";
-import { config, withBase, sourceLabel } from "../lib/examples.js";
+import { config, withBase, sourceLabel, downloadUrl, downloadName, sparseCheckout } from "../lib/examples.js";
 
 const { example } = Astro.props;
 
@@ -25,7 +25,7 @@ const badge = sourceLabel(example);
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>{example.title} | Workday Examples Hub</title>
+    <title>{example.title} | Workday Developer Program</title>
     <meta name="description" content={example.description} />
     <link rel="icon" type="image/png" href={withBase("favicon.png")} />
     <link rel="preconnect" href="https://fonts.googleapis.com" />
@@ -89,7 +89,7 @@ const badge = sourceLabel(example);
             </div>
           </div>
         </div>
-        <div class="flex shrink-0 gap-2.5">
+        <div class="flex shrink-0 flex-wrap gap-2.5">
           {example.tutorial && (
             <a
               href={example.tutorial}
@@ -104,13 +104,49 @@ const badge = sourceLabel(example);
             href={codeUrl}
             target="_blank"
             rel="noopener"
-            class="rounded-md bg-neutral-900 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-neutral-700 dark:bg-white dark:text-black dark:hover:bg-neutral-200"
+            class="rounded-md border border-neutral-200 px-4 py-2 text-sm font-medium text-neutral-700 transition-colors hover:bg-neutral-100 dark:border-neutral-800 dark:text-neutral-300 dark:hover:bg-neutral-900"
           >
             View code
           </a>
+          <a
+            href={downloadUrl(example)}
+            download={downloadName(example)}
+            class="inline-flex items-center gap-2 rounded-md bg-neutral-900 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-neutral-700 dark:bg-white dark:text-black dark:hover:bg-neutral-200"
+          >
+            <svg viewBox="0 0 24 24" width="15" height="15" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+              <path d="M12 3v12m0 0 4-4m-4 4-4-4"></path>
+              <path d="M4 17v2a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-2"></path>
+            </svg>
+            Download zip
+          </a>
         </div>
       </div>
 
+      <details class="mt-6 rounded-lg border border-neutral-200 dark:border-neutral-800">
+        <summary class="cursor-pointer select-none px-4 py-3 text-sm font-medium text-neutral-700 dark:text-neutral-300">
+          Get it with git instead
+        </summary>
+        <div class="border-t border-neutral-200 px-4 py-4 dark:border-neutral-800">
+          <p class="text-sm text-neutral-500 dark:text-neutral-400">
+            Check out only this folder and keep the git history, so you can open a pull request from the same checkout.
+            See the <a href={contributeUrl} target="_blank" rel="noopener" class="text-wd-blue hover:underline">contribution guide</a>.
+          </p>
+          <div class="relative mt-3">
+            <pre class="overflow-x-auto rounded-md bg-neutral-100 p-4 pr-24 text-[13px] leading-relaxed text-neutral-800 dark:bg-neutral-900 dark:text-neutral-200"><code id="sparse-checkout">{sparseCheckout(example)}</code></pre>
+            <button
+              type="button"
+              id="copy-sparse-checkout"
+              class="absolute right-2 top-2 rounded-md border border-neutral-200 bg-white px-2.5 py-1 text-xs font-medium text-neutral-700 transition-colors hover:bg-neutral-50 dark:border-neutral-700 dark:bg-neutral-950 dark:text-neutral-300 dark:hover:bg-neutral-800"
+            >
+              Copy
+            </button>
+          </div>
+          <p class="mt-3 text-xs text-neutral-500 dark:text-neutral-400">
+            The zip carries the same trail: its <code>SOURCE.md</code> records the commit it was built from and these commands.
+          </p>
+        </div>
+      </details>
+
       <div class="mt-10 flex flex-col gap-12 lg:flex-row">
         <article class="prose prose-neutral min-w-0 max-w-3xl flex-1 dark:prose-invert prose-headings:scroll-mt-24 prose-headings:font-semibold prose-headings:tracking-tight">
           {Content ? <Content /> : <p>This example has no README yet.</p>}
@@ -140,5 +176,27 @@ const badge = sourceLabel(example);
     </main>
 
     <Footer contributeUrl={contributeUrl} />
+
+    <script>
+      const copyButton = document.getElementById("copy-sparse-checkout");
+      const snippet = document.getElementById("sparse-checkout");
+      copyButton?.addEventListener("click", async () => {
+        try {
+          await navigator.clipboard.writeText(snippet?.textContent ?? "");
+          copyButton.textContent = "Copied";
+        } catch {
+          // Clipboard blocked: select the snippet so a manual copy works.
+          if (snippet) {
+            const range = document.createRange();
+            range.selectNodeContents(snippet);
+            const selection = window.getSelection();
+            selection?.removeAllRanges();
+            selection?.addRange(range);
+          }
+          copyButton.textContent = "Selected";
+        }
+        setTimeout(() => (copyButton.textContent = "Copy"), 1500);
+      });
+    </script>
   </body>
 </html>

site/src/components/EntryPage.astro

@@ -7,7 +7,7 @@ const { repoUrl } = Astro.props;
   <div class="mx-auto flex h-16 max-w-7xl items-center justify-between px-6">
     <a href={withBase("")} class="flex items-center gap-2.5 text-[15px] font-semibold tracking-tight">
       <img src={withBase("favicon.png")} alt="" width="24" height="24" class="h-6 w-6 rounded-full" />
-      Examples and usecases
+      Workday Developer Program
     </a>
     <a
       href={repoUrl}