docs: add initial draft of "TutorialKit API" docs

Author: AriPerkkio

docs/tutorialkit.dev/astro.config.ts

@@ -84,6 +84,10 @@ export default defineConfig({
               label: 'React Components',
               link: '/reference/react-components',
             },
+            {
+              label: 'TutorialKit API',
+              link: '/reference/tutorialkit-api',
+            },
           ],
         },
       ],

docs/tutorialkit.dev/src/content/docs/reference/tutorialkit-api.mdx

@@ -0,0 +1,256 @@
+---
+title: TutorialKit API
+description: Use TutorialKit's lower level APIs
+---
+
+TutorialKit exposes low level APIs that authors can utilize to provide highly custom experience in their tutorials.
+
+## Tutorial Store
+
+You can access Tutorial Store by importing the `tutorialkit:store` entrypoint.
+
+```ts
+import tutorialStore from "tutorialkit:store";
+```
+
+### Common types
+
+- `ReadableAtom` from [`nanostores`](https://www.npmjs.com/package/nanostores)
+
+### Properties
+
+#### `previews`
+
+Type: `ReadableAtom<PreviewInfo[]>`
+
+```ts
+import type { PreviewSchema } from '@tutorialkit/types';
+
+class PreviewInfo {
+    readonly portInfo: PortInfo;
+    title?: string;
+    pathname?: string;
+    get url(): string | undefined;
+    get port(): number;
+    get baseUrl(): string | undefined;
+    get ready(): boolean;
+    static parse(preview: Exclude<PreviewSchema, boolean>[0]): Preview;
+    static equals(a: PreviewInfo, b: PreviewInfo): boolean;
+}
+class PortInfo {
+    readonly port: number;
+    origin?: string | undefined;
+    ready: boolean;
+}
+interface Preview {
+    port: number;
+    pathname?: string;
+    title?: string;
+}
+```
+
+Instances of the preview tabs.
+
+#### `terminalConfig`
+
+Type: `ReadableAtom<TerminalConfig>`
+
+```ts
+import type { TerminalSchema } from '@tutorialkit/types';
+import type { WebContainerProcess } from '@webcontainer/api';
+
+class TerminalConfig {
+    get panels(): TerminalPanel[];
+    get activePanel(): number;
+    get defaultOpen(): boolean;
+}
+
+class TerminalPanel implements ITerminal {
+    readonly type: TerminalPanelType;
+    static panelCount: Record<TerminalPanelType, number>;
+    static resetCount(): void;
+    readonly id: string;
+    readonly title: string;
+    get terminal(): ITerminal | undefined;
+    get process(): WebContainerProcess | undefined;
+    get processOptions(): {
+        allowRedirects: boolean;
+        allowCommands: string[] | undefined;
+    } | undefined;
+    get cols(): number | undefined;
+    get rows(): number | undefined;
+    reset(): void;
+    write(data: string): void;
+    onData(callback: (data: string) => void): void;
+    attachProcess(process: WebContainerProcess): void;
+    attachTerminal(terminal: ITerminal): void;
+}
+
+interface ITerminal {
+    readonly cols?: number;
+    readonly rows?: number;
+    reset: () => void;
+    write: (data: string) => void;
+    onData: (cb: (data: string) => void) => void;
+}
+```
+
+Configuration and instances of the terminal
+
+#### `editorConfig`
+
+Type: `ReadableAtom<EditorConfig>`
+
+```ts
+class EditorConfig {
+    get visible(): boolean;
+    get fileTree(): {
+        visible: boolean;
+        allowEdits: false | string[];
+    };
+}
+```
+
+Configuration of the editor and file tree.
+
+#### `currentDocument`
+
+Type: `ReadableAtom<EditorDocument | undefined>`
+
+File that's currently open in the editor.
+
+#### `bootStatus`
+
+Type: `ReadableAtom<BootStatus>`
+
+Status of the webcontainer's booting.
+
+#### `documents`
+
+Type: `ReadableAtom<EditorDocuments>`
+
+Files that are available in the editor.
+
+#### `files`
+
+Type: `ReadableAtom<FileDescriptor[]>`
+
+Paths of the files that are available in the lesson.
+
+#### `template`
+
+Type: `Files | undefined`
+
+Files of the template.
+
+#### `selectedFile`
+
+Type: `ReadableAtom<string | undefined>`
+
+File that's currently selected in the file tree.
+
+#### `lesson`
+
+Type: `Readonly<Lesson> | undefined`
+
+Currently active lesson.
+
+### Methods
+
+#### `hasFileTree`
+
+Type: `() => boolean`
+
+#### `hasEditor`
+
+Type: `() => boolean`
+
+#### `hasPreviews`
+
+Type: `() => boolean`
+
+#### `hasTerminalPanel`
+
+Type: `() => boolean`
+
+#### `hasSolution`
+
+Type: `() => boolean`
+
+#### `unblockBoot`
+
+Type: `() => void`
+
+#### `reset`
+
+Type: `() => void`
+
+#### `solve`
+
+Type: `() => void`
+
+#### `setSelectedFile`
+
+Type: `(filePath: string | undefined) => void`
+
+#### `addFile`
+
+Type: `(filePath: string) => Promise<void>`
+
+#### `addFolder`
+
+Type: `(folderPath: string) => Promise<void>`
+
+#### `updateFile`
+
+Type: `(filePath: string, content: string) => void`
+
+#### `updateFiles`
+
+Type: `(files: Files) => void`
+
+#### `setCurrentDocumentContent`
+
+Type: `(newContent: string) => void`
+
+#### `setCurrentDocumentScrollPosition`
+
+Type: `(position: ScrollPosition) => void`
+
+#### `onTerminalResize`
+
+Type: `(cols: number, rows: number) => void`
+
+#### `onDocumentChanged`
+
+Type: `(filePath: string, callback: (document: Readonly<EditorDocument>) => void) => () => void`
+
+#### `refreshStyles`
+
+Type: `() => void`
+
+#### `takeSnapshot`
+
+Type: `() => { files: Record<string, string> }`
+
+## Tutorial Core
+
+You can access Tutorial Core by importing the `tutorialkit:core` entrypoint.
+
+```ts
+import * as core from "tutorialkit:core";
+```
+
+The Tutorial Core provides access to webcontainer APIs. You can use it for example to read and modify files on the virtual file system.
+
+### Common Types
+
+- `WebContainer` from [`@webcontainer/api`](https://www.npmjs.com/package/@webcontainer/api)
+
+### Properties
+
+#### `webcontainer`
+
+Type: `Promise<WebContainer>`
+
+Promise that resolves to the webcontainer that's running in the current lesson.

packages/astro/types.d.ts

@@ -1,9 +1,12 @@
+/* eslint-disable @blitz/lines-around-comment */
+
 declare module 'tutorialkit:store' {
   const tutorialStore: import('@tutorialkit/runtime').TutorialStore;
 
   export default tutorialStore;
 }
 
 declare module 'tutorialkit:core' {
+  /** Promise that resolves to the webcontainer that's running in the current lesson. */
   export const webcontainer: Promise<import('@webcontainer/api').WebContainer>;
 }

packages/runtime/src/store/index.ts

@@ -129,6 +129,7 @@ export class TutorialStore {
     }
   }
 
+  /** @internal */
   setLesson(lesson: Lesson, options: { ssr?: boolean } = {}) {
     if (lesson === this._lesson) {
       return;
@@ -191,50 +192,62 @@ export class TutorialStore {
     );
   }
 
+  /** Instances of the preview tabs. */
   get previews(): ReadableAtom<PreviewInfo[]> {
     return this._previewsStore.previews;
   }
 
+  /** Configuration and instances of the terminal */
   get terminalConfig(): ReadableAtom<TerminalConfig> {
     return this._terminalStore.terminalConfig;
   }
 
+  /** Configuration of the editor and file tree */
   get editorConfig(): ReadableAtom<EditorConfig> {
     return this._editorStore.editorConfig;
   }
 
+  /** File that's currently open in the editor */
   get currentDocument(): ReadableAtom<EditorDocument | undefined> {
     return this._editorStore.currentDocument;
   }
 
+  /** Status of the webcontainer's booting */
   get bootStatus(): ReadableAtom<BootStatus> {
     return bootStatus;
   }
 
+  /** Files that are available in the editor. */
   get documents(): ReadableAtom<EditorDocuments> {
     return this._editorStore.documents;
   }
 
+  /** Paths of the files that are available in the lesson */
   get files(): ReadableAtom<FileDescriptor[]> {
     return this._editorStore.files;
   }
 
+  /** Files of the template */
   get template(): Files | undefined {
     return this._lessonTemplate;
   }
 
+  /** File that's currently selected in the file tree */
   get selectedFile(): ReadableAtom<string | undefined> {
     return this._editorStore.selectedFile;
   }
 
+  /** Currently active lesson */
   get lesson(): Readonly<Lesson> | undefined {
     return this._lesson;
   }
 
+  /** @internal */
   get ref(): ReadableAtom<unknown> {
     return this._ref;
   }
 
+  /** @internal */
   get themeRef(): ReadableAtom<unknown> {
     return this._themeRef;
   }
@@ -377,6 +390,7 @@ export class TutorialStore {
     this._editorStore.updateScrollPosition(filePath, position);
   }
 
+  /** @internal */
   attachTerminal(id: string, terminal: ITerminal) {
     this._terminalStore.attachTerminal(id, terminal);
   }