feat(astro): add "Download lesson as zip" button

Author: AriPerkkio

docs/tutorialkit.dev/package.json

@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "@tutorialkit/react": "workspace:*",
-    "@webcontainer/api": "1.2.4",
+    "@webcontainer/api": "1.5.0",
     "classnames": "^2.5.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"

docs/tutorialkit.dev/src/content/docs/guides/overriding-components.mdx

@@ -46,6 +46,7 @@ When overriding `TopBar` you can place TutorialKit's default components using fo
 
 - `logo`: Logo of the application
 - `open-in-stackblitz-link`: Link for opening current lesson in StackBlitz
+- `download-button`: Button for downloading current lesson as `.zip` file
 - `theme-switch`:  Switch for changing the theme
 - `login-button`: For StackBlitz Enterprise user, the login button
 
@@ -61,6 +62,8 @@ When overriding `TopBar` you can place TutorialKit's default components using fo
 
   <LanguageSelect />
 
+  <slot name="download-button" />
+
   <slot name="open-in-stackblitz-link" />
 
   <slot name="login-button" />

docs/tutorialkit.dev/src/content/docs/reference/configuration.mdx

@@ -412,6 +412,19 @@ type TemplateType = "html" | "node" | "angular-cli" | "create-react-app" | "java
 
 ```
 
+### `downloadAsZip`
+Display a button for downloading the current lesson as `.zip` file.
+<PropertyTable inherited type="DownloadAsZip" />
+
+The `DownloadAsZip` type has the following shape:
+
+```ts
+type DownloadAsZip =
+    | boolean
+    | { filename?: string }
+
+```
+
 ##### `meta`
 
 Configures `<meta>` tags for Open Graph protocole and Twitter.

e2e/package.json

@@ -30,6 +30,7 @@
     "playwright": "^1.46.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "unocss": "^0.59.4"
+    "unocss": "^0.59.4",
+    "unzipper": "^0.12.3"
   }
 }

e2e/src/components/TopBar.astro

@@ -7,6 +7,10 @@
 
   <div class="mr-2 color-tk-text-primary">Custom Top Bar Mounted</div>
 
+  <div class="mr-2">
+    <slot name="download-button" />
+  </div>
+
   <div class="mr-2">
     <slot name="open-in-stackblitz-link" />
   </div>

e2e/test/topbar.override-components.test.ts

@@ -7,6 +7,7 @@ test('developer can override TopBar', async ({ page }) => {
   await expect(nav.getByText('Custom Top Bar Mounted')).toBeVisible();
 
   // default elements should also be visible
+  await expect(nav.getByRole('button', { name: 'Download lesson as zip-file' })).toBeVisible();
   await expect(nav.getByRole('button', { name: 'Open in StackBlitz' })).toBeVisible();
   await expect(nav.getByRole('button', { name: 'Toggle Theme' })).toBeVisible();
 });

e2e/test/topbar.test.ts

@@ -0,0 +1,78 @@
+/// <reference types="node" />
+import { readdirSync, readFileSync, rmSync } from 'node:fs';
+import type { Readable } from 'node:stream';
+import { test, expect } from '@playwright/test';
+import * as unzipper from 'unzipper';
+import { theme } from '../../packages/theme/src/theme';
+
+test('user can change theme', async ({ page }) => {
+  await page.goto('/');
+
+  const heading = page.getByRole('heading', { level: 1 });
+  const html = page.locator('html');
+
+  // default light theme
+  await expect(html).toHaveAttribute('data-theme', 'light');
+  await expect(heading).toHaveCSS('color', hexToRGB(theme.colors.gray[800]));
+
+  await page.getByRole('navigation').getByRole('button', { name: 'Toggle Theme' }).click();
+
+  await expect(html).toHaveAttribute('data-theme', 'dark');
+  await expect(heading).toHaveCSS('color', hexToRGB(theme.colors.gray[200]));
+});
+
+test('user can download project as zip', async ({ page }) => {
+  await page.goto('/', { waitUntil: 'networkidle' });
+
+  const downloadPromise = page.waitForEvent('download');
+  await page.getByRole('navigation').getByRole('button', { name: 'Download lesson as zip-file' }).click();
+
+  const download = await downloadPromise;
+  expect(download.suggestedFilename()).toBe('tests-file-tree-allow-edits-disabled.zip');
+
+  const stream = await download.createReadStream();
+  const files = await unzip(stream);
+
+  expect(files).toMatchObject({
+    './tutorial/file-on-template.js': "export default 'This file is present on template';\n",
+    './tutorial/first-level/file.js': "export default 'File in first level';\n",
+    './tutorial/first-level/second-level/file.js': "export default 'File in second level';\n",
+  });
+
+  expect(files['./tutorial/index.mjs']).toMatch("import http from 'node:http'");
+});
+
+function hexToRGB(hex: string) {
+  return `rgb(${parseInt(hex.slice(1, 3), 16)}, ${parseInt(hex.slice(3, 5), 16)}, ${parseInt(hex.slice(5, 7), 16)})`;
+}
+
+async function unzip(stream: Readable) {
+  await stream.pipe(unzipper.Extract({ path: './downloads' })).promise();
+
+  const files = readDirectoryContents('./downloads');
+  rmSync('./downloads', { recursive: true });
+
+  return files.reduce(
+    (all, current) => ({
+      ...all,
+      [current.name.replace('/downloads', '')]: current.content,
+    }),
+    {},
+  );
+}
+
+function readDirectoryContents(directory: string) {
+  const files: { name: string; content: string }[] = [];
+
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const name = `${directory}/${entry.name}`;
+
+    if (entry.isFile()) {
+      files.push({ name, content: readFileSync(name, 'utf-8') });
+    } else if (entry.isDirectory()) {
+      files.push(...readDirectoryContents(name));
+    }
+  }
+
+  return files;
+}

packages/astro/package.json

@@ -45,7 +45,7 @@
     "@tutorialkit/types": "workspace:*",
     "@types/react": "^18.3.3",
     "@unocss/reset": "^0.62.2",
-    "@webcontainer/api": "1.2.4",
+    "@webcontainer/api": "1.5.0",
     "astro": "^4.15.0",
     "astro-expressive-code": "^0.35.3",
     "chokidar": "3.6.0",

packages/astro/src/default/components/DownloadButton.tsx

@@ -0,0 +1,44 @@
+import { tutorialStore, webcontainer as webcontainerPromise } from './webcontainer.js';
+
+export function DownloadButton() {
+  return (
+    <button
+      title="Download lesson as zip-file"
+      className="flex items-center text-2xl text-tk-elements-topBar-iconButton-iconColor hover:text-tk-elements-topBar-iconButton-iconColorHover transition-theme bg-tk-elements-topBar-iconButton-backgroundColor hover:bg-tk-elements-topBar-iconButton-backgroundColorHover p-1 rounded-md"
+      onClick={onClick}
+    >
+      <div className="i-ph-download-simple" />
+    </button>
+  );
+}
+
+async function onClick() {
+  const lesson = tutorialStore.lesson;
+
+  if (!lesson) {
+    throw new Error('Missing lesson');
+  }
+
+  const webcontainer = await webcontainerPromise;
+  const data = await webcontainer.export('/home/tutorial', { format: 'zip', excludes: ['node_modules'] });
+
+  let filename =
+    typeof lesson.data.downloadAsZip === 'object'
+      ? lesson.data.downloadAsZip.filename
+      : `${lesson.part.id}-${lesson.chapter.id}-${lesson.id}.zip`;
+
+  if (!filename.endsWith('.zip')) {
+    filename += '.zip';
+  }
+
+  const link = document.createElement('a');
+  link.style.display = 'none';
+  link.download = filename;
+  link.href = URL.createObjectURL(new Blob([data], { type: 'application/zip' }));
+
+  document.body.appendChild(link);
+  link.click();
+
+  document.body.removeChild(link);
+  URL.revokeObjectURL(link.href);
+}

packages/astro/src/default/components/TopBar.astro

@@ -4,6 +4,10 @@
   <div class="flex flex-1">
     <slot name="logo" />
   </div>
+
+  <div class="mr-2">
+    <slot name="download-button" />
+  </div>
   <div class="mr-2">
     <slot name="open-in-stackblitz-link" />
   </div>