feat: add template.visibleFiles option

Author: AriPerkkio

docs/tutorialkit.dev/src/content/docs/guides/creating-content.mdx

@@ -3,6 +3,7 @@ title: Content creation
 description: 'Creating content in TutorialKit.'
 ---
 import { FileTree } from '@astrojs/starlight/components';
+import { Tabs, TabItem } from '@astrojs/starlight/components';
 
 From an information architecture perspective, tutorial content is divided into **parts**, which are further divided into **chapters**, each consisting of **lessons**.
 
@@ -110,6 +111,19 @@ template: my-advanced-template
 
 This declaration will make TutorialKit use the `src/templates/my-advanced-template` directory as the base for the lesson.
 
+By default files in template are not shown in the code editor.
+To make them visible, you can use `visibleFiles` option.
+This can reduce repetition when you want to show same files visible in multiple lessons.
+
+```markdown {5}
+---
+title: Advanced Topics
+template:
+  name: my-advanced-template
+  visibleFiles: ['src/index.js', '**/utils/**']
+---
+```
+
 If you start having a lot of templates and they all share some files, you can create a shared template that they all extend. This way, you can keep the shared files in one place and avoid duplication. To do that, you need to specify the `extends` property in the template's `.tk-config.json` file:
 
 ```json
@@ -144,3 +158,75 @@ src/templates
     │   # Overrides "index.js" from "shared-template"
     └── index.js
 ```
+
+## Editor File Visibility
+
+Editor's files are resolved in three steps. Each step overrides previous one:
+
+1. Display files matching `template.visibleFiles` (lowest priority)
+2. Display files from `_files` directory
+3. When solution is revealed, display files from `_solution` directory. (highest priority)
+
+<Tabs syncKey="file-visibilty">
+  <TabItem label="Initially">
+
+```markdown ins=/.{24}├── (first.js)/ ins=/└── (second.js)/ ins=/third.js/
+---
+template:
+  name: default
+  visibleFiles: ['src/**']
+---
+
+src
+├── content
+│   └── tutorial
+│       └── 1-basics
+│           └── 1-introduction
+│               └── 1-welcome
+│                   ├── _files
+│                   │   ├── first.js
+│                   │   └── second.js
+│                   └── _solution
+│                       └── first.js
+└── templates
+    └── default
+        ├── src
+        │   ├── first.js
+        │   ├── second.js
+        │   └── third.js
+        └── package.json
+```
+
+  </TabItem>
+
+  <TabItem label="After solution is revealed">
+
+```markdown ins=/└── (first.js)/ ins=/└── (second.js)/ ins=/third.js/
+---
+template:
+  name: default
+  visibleFiles: ['src/**']
+---
+
+src
+├── content
+│   └── tutorial
+│       └── 1-basics
+│           └── 1-introduction
+│               └── 1-welcome
+│                   ├── _files
+│                   │   ├── first.js
+│                   │   └── second.js
+│                   └── _solution
+│                       └── first.js
+└── templates
+    └── default
+        ├── src
+        │   ├── first.js
+        │   ├── second.js
+        │   └── third.js
+        └── package.json
+```
+
+  </TabItem>
+</Tabs>

packages/astro/package.json

@@ -51,6 +51,7 @@
     "kleur": "4.1.5",
     "mdast-util-directive": "^3.0.0",
     "mdast-util-to-markdown": "^2.1.0",
+    "micromatch": "^4.0.7",
     "nanostores": "^0.10.3",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
@@ -63,6 +64,7 @@
   "devDependencies": {
     "@tutorialkit/types": "workspace:*",
     "@types/mdast": "^4.0.4",
+    "@types/micromatch": "^4.0.9",
     "esbuild": "^0.20.2",
     "esbuild-node-externals": "^1.13.1",
     "execa": "^9.2.0",

packages/astro/src/default/utils/content.ts

@@ -1,13 +1,16 @@
 import type { ChapterSchema, Lesson, LessonSchema, PartSchema, Tutorial, TutorialSchema } from '@tutorialkit/types';
 import { interpolateString } from '@tutorialkit/types';
 import { getCollection } from 'astro:content';
+import mm from 'micromatch';
 import path from 'node:path';
 import { DEFAULT_LOCALIZATION } from './content/default-localization';
 import { squash } from './content/squash.js';
 import { logger } from './logger';
 import { joinPaths } from './url';
 import { getFilesRefList } from './content/files-ref';
 
+const TEMPLATES_DIR = path.join(process.cwd(), 'src/templates');
+
 export async function getTutorial(): Promise<Tutorial> {
   const collection = sortCollection(await getCollection('tutorial'));
 
@@ -253,6 +256,22 @@ export async function getTutorial(): Promise<Tutorial> {
       ),
     };
 
+    if (lesson.data.template && typeof lesson.data.template !== 'string' && lesson.data.template.visibleFiles?.length) {
+      const templateFilesRef = await getFilesRefList(lesson.data.template.name, TEMPLATES_DIR);
+
+      for (const filename of templateFilesRef[1]) {
+        if (lesson.files[1].includes(filename)) {
+          continue;
+        }
+
+        if (mm.isMatch(filename, lesson.data.template.visibleFiles, { format: formatTemplateFile })) {
+          lesson.files[1].push(filename);
+        }
+      }
+
+      lesson.files[1].sort();
+    }
+
     if (prevLesson) {
       const partSlug = _tutorial.parts[prevLesson.part.id].slug;
       const chapterSlug = _tutorial.parts[prevLesson.part.id].chapters[prevLesson.chapter.id].slug;
@@ -321,6 +340,15 @@ function getSlug(entry: CollectionEntryTutorial) {
   return slug;
 }
 
+function formatTemplateFile(filename: string) {
+  // compare files without leading "/" so that patterns like ["src/index.js"] match "/src/index.js"
+  if (filename.startsWith('/')) {
+    return filename.substring(1);
+  }
+
+  return filename;
+}
+
 interface CollectionEntryTutorial {
   id: string;
   slug: string;

packages/cli/src/commands/eject/index.ts

@@ -25,6 +25,8 @@ const REQUIRED_DEPENDENCIES = [
   '@nanostores/react',
   'kleur',
   '@stackblitz/sdk',
+  'micromatch',
+  '@types/micromatch',
 ];
 
 export function ejectRoutes(flags: Arguments) {
@@ -111,6 +113,7 @@ async function _eject(flags: EjectOptions) {
   for (const dep of REQUIRED_DEPENDENCIES) {
     if (!(dep in pkgJson.dependencies) && !(dep in pkgJson.devDependencies)) {
       pkgJson.dependencies[dep] = astroIntegrationPkgJson.dependencies[dep];
+      pkgJson.devDependencies[dep] = astroIntegrationPkgJson.devDependencies[dep];
 
       newDependencies.push(dep);
     }

packages/cli/tests/__snapshots__/create-tutorial.test.ts.snap

@@ -75,6 +75,7 @@ exports[`create a project 1`] = `
   "src/templates/default/package.json",
   "src/templates/default/src",
   "src/templates/default/src/index.js",
+  "src/templates/default/src/template-only-file.js",
   "src/templates/vite-app",
   "src/templates/vite-app-2",
   "src/templates/vite-app-2/.tk-config.json",
@@ -286,6 +287,7 @@ exports[`create and eject a project 1`] = `
   "src/templates/default/package.json",
   "src/templates/default/src",
   "src/templates/default/src/index.js",
+  "src/templates/default/src/template-only-file.js",
   "src/templates/vite-app",
   "src/templates/vite-app-2",
   "src/templates/vite-app-2/.tk-config.json",

packages/runtime/src/store/index.ts

@@ -42,10 +42,18 @@ export class TutorialStore {
   private _ref: number = 1;
   private _themeRef = atom(1);
 
+  /** Files from lesson's `_files` directory */
   private _lessonFiles: Files | undefined;
+
+  /** Files from lesson's `_solution` directory */
   private _lessonSolution: Files | undefined;
+
+  /** All files from `template` directory */
   private _lessonTemplate: Files | undefined;
 
+  /** Files from `template` directory that match `template.visibleFiles` patterns */
+  private _visibleTemplateFiles: Files | undefined;
+
   /**
    * Whether or not the current lesson is fully loaded in WebContainer
    * and in every stores.
@@ -165,15 +173,17 @@ export class TutorialStore {
 
         signal.throwIfAborted();
 
-        this._lessonTemplate = template;
         this._lessonFiles = files;
         this._lessonSolution = solution;
+        this._lessonTemplate = template;
+        this._visibleTemplateFiles = filterEntries(template, lesson.files[1]);
 
-        this._editorStore.setDocuments(files);
+        const editorFiles = { ...this._visibleTemplateFiles, ...this._lessonFiles };
+        this._editorStore.setDocuments(editorFiles);
 
         if (lesson.data.focus === undefined) {
           this._editorStore.setSelectedFile(undefined);
-        } else if (files[lesson.data.focus] !== undefined) {
+        } else if (editorFiles[lesson.data.focus] !== undefined) {
           this._editorStore.setSelectedFile(lesson.data.focus);
         }
 
@@ -283,8 +293,10 @@ export class TutorialStore {
       return;
     }
 
-    this._editorStore.setDocuments(this._lessonFiles);
-    this._runner.updateFiles(this._lessonFiles);
+    const files = { ...this._visibleTemplateFiles, ...this._lessonFiles };
+
+    this._editorStore.setDocuments(files);
+    this._runner.updateFiles(files);
   }
 
   solve() {
@@ -294,7 +306,7 @@ export class TutorialStore {
       return;
     }
 
-    const files = { ...this._lessonFiles, ...this._lessonSolution };
+    const files = { ...this._visibleTemplateFiles, ...this._lessonFiles, ...this._lessonSolution };
 
     this._editorStore.setDocuments(files);
     this._runner.updateFiles(files);
@@ -361,3 +373,7 @@ export class TutorialStore {
     return this._runner.takeSnapshot();
   }
 }
+
+function filterEntries<T extends object>(obj: T, filter: string[]) {
+  return Object.fromEntries(Object.entries(obj).filter(([entry]) => filter.includes(entry)));
+}

packages/template/src/content/tutorial/1-basics/1-introduction/1-welcome/content.md

@@ -1,7 +1,7 @@
 ---
 type: lesson
 title: Welcome to TutorialKit
-focus: /src/index.js
+focus: /src/template-only-file.js
 previews: [8080]
 mainCommand: ['node -e setTimeout(()=>{},10_000)', 'Running dev server']
 prepareCommands:
@@ -13,6 +13,7 @@ terminal:
   panels: ['terminal', 'output']
 template:
   name: default
+  visibleFiles: ['src/template-only-file.js']
 ---
 
 # Kitchen Sink [Heading 1]

packages/template/src/templates/default/src/template-only-file.js

@@ -0,0 +1 @@
+export default 'This file is only present in template';

packages/types/src/schemas/common.spec.ts

@@ -358,6 +358,16 @@ describe('webcontainerSchema', () => {
     }).not.toThrow();
   });
   it('should allow specifying the template by object type', () => {
+    expect(() => {
+      webcontainerSchema.parse({
+        template: {
+          name: 'default',
+          visibleFiles: ['**/fixture.json', '*/tests/*'],
+        },
+      });
+    }).not.toThrow();
+  });
+  it('should allow specifying the template to omit visibleFiles', () => {
     expect(() => {
       webcontainerSchema.parse({
         template: {

packages/types/src/schemas/common.ts

@@ -182,6 +182,9 @@ export const webcontainerSchema = commandsSchema.extend({
       z.strictObject({
         // name of the template
         name: z.string(),
+
+        // list of globs of files that should be visible
+        visibleFiles: z.array(z.string()).optional(),
       }),
     ])
     .describe(