Merge branch 'main' into docs-file-imports

Author: kevinzunigacuellar

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

@@ -403,3 +403,47 @@ type OpenInStackBlitz =
 type TemplateType = "html" | "node" | "angular-cli" | "create-react-app" | "javascript" | "polymer" | "typescript" | "vue"
 
 ```
+
+## Configure the Tutorialkit Astro integration
+
+`@tutorialkit/astro` is an integration for Astro. You can configure the integration in your `astro.config.ts` file.
+
+```ts "tutorialkit()" title="astro.config.ts"
+import tutorialkit from "@tutorialkit/astro";
+import { defineConfig } from "astro/config";
+
+export default defineConfig({
+  devToolbar: {
+    enabled: false,
+  },
+  integrations: [
+    tutorialkit(),
+  ],
+});
+```
+
+You can pass the following options to the `tutorialkit` integration:
+
+### `components`
+
+**type**: `OverrideComponentsOptions`
+
+Provide the path to the components you want to override.
+
+```ts
+tutorialkit({
+  components: {
+    TopBar: './src/components/CustomTopBar.astro',
+  },
+});
+```
+
+See [Overriding Components](/guides/overriding-components/) for details of all the components that you can override.
+
+### `defaultRoutes`
+
+**type**: `boolean | "tutorial-only"`<br/>
+**default**: `true`
+
+Controls whether the tutorial routes are automatically added to your project. When set to `true`, it additionally adds a redirect from `/` to the first tutorial.
+Use `"tutorial-only"` to only add the tutorial routes without the redirect.

e2e/src/content/tutorial/tests/filesystem/meta.md

@@ -1,4 +1,4 @@
 ---
 type: chapter
-title: filesystem
+title: File system
 ---

e2e/src/content/tutorial/tests/lesson-order/1-lesson/content.md

@@ -0,0 +1,6 @@
+---
+type: lesson
+title: Page one
+---
+
+# Lesson order test - Page one

e2e/src/content/tutorial/tests/lesson-order/2-lesson/content.md

@@ -0,0 +1,6 @@
+---
+type: lesson
+title: Page two
+---
+
+# Lesson order test - Page two

e2e/src/content/tutorial/tests/lesson-order/3-lesson/content.md

@@ -0,0 +1,6 @@
+---
+type: lesson
+title: Page three
+---
+
+# Lesson order test - Page three

e2e/src/content/tutorial/tests/lesson-order/meta.md

@@ -0,0 +1,8 @@
+---
+type: chapter
+title: Lesson order
+lessons:
+  - 2-lesson
+  - 3-lesson
+  - 1-lesson
+---

e2e/test/lesson-order.test.ts

@@ -0,0 +1,22 @@
+import { test, expect } from '@playwright/test';
+
+const BASE_URL = '/tests/lesson-order';
+
+test('developer can configure custom order for lessons', async ({ page }) => {
+  await page.goto(`${BASE_URL}/1-lesson`);
+  await expect(page.getByRole('heading', { level: 1, name: 'Lesson order test - Page one' })).toBeVisible();
+
+  // navigation select can take a while to hydrate on page load, click until responsive
+  await expect(async () => {
+    const button = page.getByRole('button', { name: 'Tests / Lesson order / Page one' });
+    await button.click();
+    await expect(page.locator('[data-state="open"]', { has: button })).toBeVisible({ timeout: 50 });
+  }).toPass();
+
+  const list = page.getByRole('region', { name: 'Lesson order' });
+
+  // configured ordered is [2, 3, 1]
+  await expect(list.getByRole('listitem').nth(0)).toHaveText('Page two');
+  await expect(list.getByRole('listitem').nth(1)).toHaveText('Page three');
+  await expect(list.getByRole('listitem').nth(2)).toHaveText('Page one');
+});

e2e/test/navigation.test.ts

@@ -23,7 +23,13 @@ test('user can navigate between lessons using nav bar links', async ({ page }) =
 test('user can navigate between lessons using breadcrumbs', async ({ page }) => {
   await page.goto(`${BASE_URL}/page-one`);
 
-  await page.getByRole('button', { name: 'Tests / Navigation / Page one' }).click({ force: true });
+  // navigation select can take a while to hydrate on page load, click until responsive
+  await expect(async () => {
+    const button = page.getByRole('button', { name: 'Tests / Navigation / Page one' });
+    await button.click();
+    await expect(page.locator('[data-state="open"]', { has: button })).toBeVisible({ timeout: 50 });
+  }).toPass();
+
   await page.getByRole('region', { name: 'Navigation' }).getByRole('link', { name: 'Page three' }).click();
 
   await expect(page.getByRole('heading', { level: 1, name: 'Navigation test - Page three' })).toBeVisible();

e2e/test/terminal.test.ts

@@ -15,10 +15,14 @@ test('user can open terminal', async ({ page }) => {
   // await expect(tab).not.toBeVisible();
   // await expect(panel).not.toBeVisible();
 
-  await page.getByRole('button', { name: 'Toggle Terminal' }).click();
+  // terminal toggle can take a while to hydrate on page load, click until responsive
+  await expect(async () => {
+    await page.getByRole('button', { name: 'Toggle Terminal' }).click();
+
+    await expect(tab).toBeVisible({ timeout: 100 });
+    await expect(panel).toBeVisible({ timeout: 100 });
+  }).toPass();
 
-  await expect(tab).toBeVisible();
-  await expect(panel).toBeVisible();
   await expect(panel).toContainText('~/tutorial', { useInnerText: true });
 });
 

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

@@ -1,6 +1,7 @@
 import * as content from 'astro:content';
 import { describe, expect, test, vi, type TaskContext } from 'vitest';
 import { getTutorial, type CollectionEntryTutorial } from './content';
+import { logger } from './logger';
 
 const getCollection = vi.mocked<() => Omit<CollectionEntryTutorial, 'render'>[]>(content.getCollection);
 vi.mock('astro:content', () => ({ getCollection: vi.fn() }));
@@ -11,6 +12,8 @@ vi.mock(import('@tutorialkit/types'), async (importOriginal) => ({
   DEFAULT_LOCALIZATION: { mocked: 'default localization' } as any,
 }));
 
+vi.mock(import('./logger'), async (importOriginal) => importOriginal());
+
 expect.addSnapshotSerializer({
   serialize: (val) => JSON.stringify(val, null, 2),
   test: (value) => !(value instanceof Error),
@@ -95,6 +98,34 @@ test('multiple parts', async (ctx) => {
   await expect(collection).toMatchFileSnapshot(snapshotName(ctx));
 });
 
+test('lessons with identical names in different chapters', async () => {
+  getCollection.mockReturnValueOnce([
+    { id: 'meta.md', ...tutorial },
+    { id: '1-part/meta.md', ...part },
+
+    { id: '1-part/1-chapter/meta.md', ...chapter },
+    {
+      id: '1-part/1-chapter/identical-lesson-name/content.md',
+      ...lesson,
+      data: { ...lesson.data, focus: '/first.js' },
+    },
+
+    { id: '1-part/2-chapter/meta.md', ...chapter },
+    {
+      id: '1-part/2-chapter/identical-lesson-name/content.md',
+      ...lesson,
+      data: { ...lesson.data, focus: '/second.js' },
+    },
+  ]);
+
+  const collection = await getTutorial();
+  const chapters = collection.parts['1-part'].chapters;
+
+  // verify that lesson.id is not used to define what makes a lesson unique (part.id + chapter.id too)
+  expect(chapters['1-chapter'].lessons['identical-lesson-name']).toBeDefined();
+  expect(chapters['2-chapter'].lessons['identical-lesson-name']).toBeDefined();
+});
+
 describe('metadata inheriting', () => {
   test('lesson inherits metadata from tutorial', async () => {
     const data: CollectionEntryTutorial['data'] = {
@@ -212,6 +243,33 @@ describe('ordering', () => {
     expect(parts['2-part'].order).toBe(2);
   });
 
+  test('parts not mention in order are excluded ', async () => {
+    vi.spyOn(logger, 'warn').mockImplementationOnce(vi.fn());
+
+    getCollection.mockReturnValueOnce([
+      {
+        id: 'meta.md',
+        ...tutorial,
+        data: { ...tutorial.data, parts: ['2-part', '1-part'] },
+      },
+      { id: '2-part/meta.md', ...part },
+      { id: 'excluded-part/meta.md', ...part },
+      { id: '1-part/meta.md', ...part },
+    ]);
+
+    const collection = await getTutorial();
+    const parts = collection.parts;
+
+    expect(Object.keys(parts)).toHaveLength(2);
+    expect(parts['excluded-part']).toBeUndefined();
+    expect(parts['1-part']).toBeDefined();
+    expect(parts['2-part']).toBeDefined();
+
+    expect(vi.mocked(logger.warn).mock.calls[0][0]).toMatchInlineSnapshot(
+      `"An order was specified for the parts of the tutorial but 'excluded-part' is not included so it won't be visible."`,
+    );
+  });
+
   test('chapters are ordered by default', async () => {
     getCollection.mockReturnValueOnce([
       { id: 'meta.md', ...tutorial },
@@ -246,6 +304,30 @@ describe('ordering', () => {
     expect(chapters['2-chapter'].order).toBe(2);
   });
 
+  test('chapters not mention in order are excluded ', async () => {
+    vi.spyOn(logger, 'warn').mockImplementationOnce(vi.fn());
+
+    getCollection.mockReturnValueOnce([
+      { id: 'meta.md', ...tutorial },
+      { id: '1-part/meta.md', ...part, data: { ...part.data, chapters: ['2-chapter', '1-chapter'] } },
+      { id: '1-part/2-chapter/meta.md', ...chapter },
+      { id: '1-part/excluded-chapter/meta.md', ...chapter },
+      { id: '1-part/1-chapter/meta.md', ...chapter },
+    ]);
+
+    const collection = await getTutorial();
+    const chapters = collection.parts['1-part'].chapters;
+
+    expect(Object.keys(chapters)).toHaveLength(2);
+    expect(chapters['excluded-part']).toBeUndefined();
+    expect(chapters['1-chapter']).toBeDefined();
+    expect(chapters['2-chapter']).toBeDefined();
+
+    expect(vi.mocked(logger.warn).mock.calls[0][0]).toMatchInlineSnapshot(
+      `"An order was specified for part '1-part' but chapter 'excluded-chapter' is not included, so it won't be visible."`,
+    );
+  });
+
   test('lessons are ordered by default', async () => {
     getCollection.mockReturnValueOnce([
       { id: 'meta.md', ...tutorial },
@@ -288,6 +370,34 @@ describe('ordering', () => {
     expect(lessons['1-lesson'].order).toBe(1);
     expect(lessons['2-lesson'].order).toBe(2);
   });
+
+  test('lessons not mention in order are excluded ', async () => {
+    vi.spyOn(logger, 'warn').mockImplementationOnce(vi.fn());
+
+    getCollection.mockReturnValueOnce([
+      { id: 'meta.md', ...tutorial },
+      { id: '1-part/meta.md', ...part },
+      {
+        id: '1-part/1-chapter/meta.md',
+        ...chapter,
+        data: { ...chapter.data, lessons: ['2-lesson', '1-lesson'] },
+      },
+      { id: '1-part/1-chapter/excluded-lesson/meta.md', ...lesson },
+      { id: '1-part/1-chapter/1-lesson/meta.md', ...lesson },
+      { id: '1-part/1-chapter/2-lesson/meta.md', ...lesson },
+    ]);
+
+    const collection = await getTutorial();
+    const lessons = collection.parts['1-part'].chapters['1-chapter'].lessons;
+
+    expect(Object.keys(lessons)).toHaveLength(2);
+    expect(lessons['1-lesson']).toBeDefined();
+    expect(lessons['2-lesson']).toBeDefined();
+
+    expect(vi.mocked(logger.warn).mock.calls[0][0]).toMatchInlineSnapshot(
+      `"An order was specified for chapter '1-chapter' but lesson 'excluded-lesson' is not included, so it won't be visible."`,
+    );
+  });
 });
 
 describe('missing parts', () => {