Downloading the instructions (#1160)

## What's Changed?

- Includes instructions in the project download if there are any
- Adds a list of reserved file names which includes `INSTRUCTIONS.md` to
prevent clashes

Closes
RaspberryPiFoundation/digital-editor-issues#374

CHANGELOG.md

@@ -9,6 +9,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ### Added
 
 - Support for the `outputPanels` attribute in the `PyodideRunner` (#1157)
+- Downloading project instructions (#1160)
+
+### Changed
+
+- Made `INSTRUCTIONS.md` a reserved file name (#1160)
 
 ## [0.28.14] - 2025-01-06
 

src/components/DownloadButton/DownloadButton.jsx

@@ -39,6 +39,10 @@ const DownloadButton = (props) => {
 
     const zip = new JSZip();
 
+    if (project.instructions) {
+      zip.file("INSTRUCTIONS.md", project.instructions);
+    }
+
     project.components.forEach((file) => {
       zip.file(`${file.name}.${file.extension}`, file.content);
     });

src/components/DownloadButton/DownloadButton.test.js

@@ -25,6 +25,7 @@ describe("Downloading project with name set", () => {
         project: {
           name: "My epic project",
           identifier: "hello-world-project",
+          instructions: "print hello world to the console",
           components: [
             {
               name: "main",
@@ -53,6 +54,18 @@ describe("Downloading project with name set", () => {
     expect(downloadButton).toBeInTheDocument();
   });
 
+  test("Clicking download zips instructions", async () => {
+    fireEvent.click(downloadButton);
+    const JSZipInstance = JSZip.mock.instances[0];
+    const mockFile = JSZipInstance.file;
+    await waitFor(() =>
+      expect(mockFile).toHaveBeenCalledWith(
+        "INSTRUCTIONS.md",
+        "print hello world to the console",
+      ),
+    );
+  });
+
   test("Clicking download zips project file content", async () => {
     fireEvent.click(downloadButton);
     const JSZipInstance = JSZip.mock.instances[0];
@@ -123,3 +136,48 @@ describe("Downloading project with no name set", () => {
     );
   });
 });
+
+describe("Downloading project with no instructions set", () => {
+  let downloadButton;
+
+  beforeEach(() => {
+    JSZip.mockClear();
+    const middlewares = [];
+    const mockStore = configureStore(middlewares);
+    const initialState = {
+      editor: {
+        project: {
+          name: "My epic project",
+          identifier: "hello-world-project",
+          components: [
+            {
+              name: "main",
+              extension: "py",
+              content: "",
+            },
+          ],
+          image_list: [],
+        },
+      },
+    };
+    const store = mockStore(initialState);
+    render(
+      <Provider store={store}>
+        <DownloadButton buttonText="Download" Icon={() => {}} />
+      </Provider>,
+    );
+    downloadButton = screen.queryByText("Download").parentElement;
+  });
+
+  test("Clicking download button does not zip instructions", async () => {
+    fireEvent.click(downloadButton);
+    const JSZipInstance = JSZip.mock.instances[0];
+    const mockFile = JSZipInstance.file;
+    await waitFor(() =>
+      expect(mockFile).not.toHaveBeenCalledWith(
+        "INSTRUCTIONS.md",
+        expect.anything(),
+      ),
+    );
+  });
+});

src/components/Modals/NewFileModal.test.js

@@ -81,6 +81,17 @@ describe("Testing the new file modal", () => {
     expect(store.getActions()).toEqual(expectedActions);
   });
 
+  test("Reserved file name throws error", () => {
+    fireEvent.change(inputBox, { target: { value: "INSTRUCTIONS.md" } });
+    fireEvent.click(saveButton);
+    const expectedActions = [
+      setNameError("filePanel.errors.reservedFileName", {
+        fileName: "INSTRUCTIONS.md",
+      }),
+    ];
+    expect(store.getActions()).toEqual(expectedActions);
+  });
+
   test("Unsupported extension throws error", () => {
     fireEvent.change(inputBox, { target: { value: "file1.js" } });
     fireEvent.click(saveButton);

src/components/Modals/RenameFileModal.test.js

@@ -91,6 +91,17 @@ describe("Testing the rename file modal", () => {
     expect(store.getActions()).toEqual(expectedActions);
   });
 
+  test("Reserved file name throws error", () => {
+    fireEvent.change(inputBox, { target: { value: "INSTRUCTIONS.md" } });
+    fireEvent.click(saveButton);
+    const expectedActions = [
+      setNameError("filePanel.errors.reservedFileName", {
+        fileName: "INSTRUCTIONS.md",
+      }),
+    ];
+    expect(store.getActions()).toEqual(expectedActions);
+  });
+
   test("Unchanged file name does not throw error", () => {
     fireEvent.click(saveButton);
     const expectedActions = [

src/utils/componentNameValidation.js

@@ -5,6 +5,8 @@ const allowedExtensions = {
   html: ["html", "css", "js"],
 };
 
+const reservedFileNames = ["INSTRUCTIONS.md"];
+
 const allowedExtensionsString = (projectType, t) => {
   const extensionsList = allowedExtensions[projectType];
   if (extensionsList.length === 1) {
@@ -19,6 +21,7 @@ const allowedExtensionsString = (projectType, t) => {
 const isValidFileName = (fileName, projectType, componentNames) => {
   const extension = fileName.split(".").slice(1).join(".");
   if (
+    !reservedFileNames.includes(fileName) &&
     allowedExtensions[projectType].includes(extension) &&
     !componentNames.includes(fileName) &&
     fileName.split(" ").length === 1
@@ -44,6 +47,10 @@ export const validateFileName = (
     (currentFileName && fileName === currentFileName)
   ) {
     callback();
+  } else if (reservedFileNames.includes(fileName)) {
+    dispatch(
+      setNameError(t("filePanel.errors.reservedFileName", { fileName })),
+    );
   } else if (componentNames.includes(fileName)) {
     dispatch(setNameError(t("filePanel.errors.notUnique")));
   } else if (fileName.split(" ").length > 1) {

src/utils/i18n.js

@@ -130,6 +130,8 @@ i18n
           },
           filePanel: {
             errors: {
+              reservedFileName:
+                "{{fileName}} is a reserved file name. Please choose a different name.",
               containsSpaces: "File names must not contain spaces.",
               generalError: "Error",
               notUnique: "File names must be unique.",