@dolphy-app/extension-sdk 0.3.0 → 0.5.0

package/docs/recipe-import-export.md

@@ -0,0 +1,236 @@
+# Recipe: an importer and an exporter
+
+An importer turns a file the user picked into a new course; an exporter turns a
+course (or the learning progress) into a file the user saves. Your code only
+handles strings: the app shows the file dialogs, checks what you return with the
+course compiler, and writes to disk. This recipe has no template of its own:
+start from `blank` and replace the three files below, which are checked as a
+whole project. See [quick-start.md](quick-start.md) for the commands.
+
+## The manifest
+
+File `extension.json` (import-export):
+
+```json
+{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
+  "id": "acme.hello",
+  "version": "0.1.0",
+  "apiVersion": 1,
+  "name": "Hello cards",
+  "description": "Import flashcards from a CSV file and export a course back to CSV.",
+  "author": "your-github-login",
+  "tags": ["content"]
+}
+```
+
+The manifest holds the identity only; the importer and the exporter are
+registered by the code.
+
+## The code
+
+File `src/index.ts` (import-export):
+
+```ts
+import { defineServer } from '@dolphy-app/extension-sdk';
+import type {
+  CourseExportInput,
+  TextImportInput,
+} from '@dolphy-app/extension-sdk';
+
+const json = (value: unknown): string => `${JSON.stringify(value, null, 2)}\n`;
+
+const courseIdOf = (fileName: string): string =>
+  fileName
+    .replace(/\.csv$/i, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '') || 'cards';
+
+export const server = defineServer((s) => {
+  s.registerImporter({
+    id: 'acme.hello.import',
+    title: { en: 'Cards from CSV', ru: 'Карточки из CSV' },
+    accept: ['.csv'],
+    input: 'text',
+    // one line "front,back" is one flashcard; the paths are relative to the
+    // new course directory the app creates
+    run: ({ name, text }: TextImportInput) => {
+      const rows = text.split(/\r?\n/).filter((line) => line.trim() !== '');
+      if (rows.length === 0) throw new Error('The file has no rows');
+      const course = courseIdOf(name);
+      const lesson = `${course}::cards`;
+      const files: Record<string, string> = {
+        [`${course}/course_manifest.json`]: json({
+          id: course,
+          name: name.replace(/\.csv$/i, ''),
+          dependencies: [],
+          encompassed: [],
+          superseded: [],
+        }),
+        [`${course}/cards/lesson_manifest.json`]: json({
+          id: lesson,
+          name: 'Cards',
+          course_id: course,
+          dependencies: [],
+          encompassed: [],
+          superseded: [],
+        }),
+      };
+      rows.forEach((row, index) => {
+        const comma = row.indexOf(',');
+        if (comma <= 0 || comma === row.length - 1) {
+          throw new Error(`Row ${index + 1}: expected "front,back"`);
+        }
+        const dir = `${course}/cards/c${index + 1}`;
+        files[`${dir}/exercise_manifest.json`] = json({
+          id: `${lesson}::c${index + 1}`,
+          name: `Card ${index + 1}`,
+          lesson_id: lesson,
+          course_id: course,
+          exercise_type: 'Declarative',
+          exercise_asset: {
+            FlashcardAsset: { front_path: 'front.md', back_path: 'back.md' },
+          },
+        });
+        files[`${dir}/front.md`] = `${row.slice(0, comma).trim()}\n`;
+        files[`${dir}/back.md`] = `${row.slice(comma + 1).trim()}\n`;
+      });
+      return { files };
+    },
+  });
+
+  s.registerExporter({
+    id: 'acme.hello.export',
+    title: { en: 'Course to CSV', ru: 'Курс в CSV' },
+    scope: 'course',
+    // the snapshot holds the text files of the chosen course, paths relative
+    // to the course directory
+    run: ({ title, files }: CourseExportInput) => {
+      const cell = (text: string): string => text.trim().replace(/\s+/g, ' ');
+      const fronts = Object.keys(files)
+        .filter((path) => path.endsWith('/front.md'))
+        .sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
+      const rows = fronts.map((path) => {
+        const back = files[`${path.slice(0, -'front.md'.length)}back.md`];
+        return `${cell(files[path] ?? '')},${cell(back ?? '')}`;
+      });
+      return {
+        filename: `${title.replace(/[\\/]/g, '-').slice(0, 100)}.csv`,
+        text: `${rows.join('\n')}\n`,
+      };
+    },
+  });
+});
+```
+
+- `server.registerImporter({ id, title, accept, input, run })`: `title` (up to 60
+  characters) is a `LocalizedText`; `accept` is 1–8 unique lower-case file
+  extensions such as `.csv`; `input` is `text` (the handler gets the file as a
+  UTF-8 string) or `bytes` (a `Uint8Array`). `server.registerExporter({ id,
+  title, scope, run })` has a `scope`: `course` or `progress`. At most 8 of each
+  per extension.
+- The user choosing the file is the consent, and your code never sees a path. A
+  `progress` exporter reads `server.stats`.
+- The importer appears in the palette as "Import: Cards from CSV", the exporter
+  as "Export: Course to CSV", and both have buttons in Settings → Library.
+- An importer handler gets `{ name, text }` (or `{ name, bytes }`) and returns
+  `{ files: Record<path, text> }`: the files of a new directory in the library
+  (`imported/<extension id>-<file name>`). At most 5000 files, 2 MiB each and
+  20 MiB in all; a path is relative, uses `/`, and has no `..`, empty or
+  dot-leading segment, backslash, control character, or case-only duplicate.
+  Binary files are not supported: every file is text.
+- The app compiles the tree before it writes anything and shows a summary
+  (courses, lessons, exercises) and diagnostics. With an error the user cannot
+  import, and nothing is left on disk. Importing the same file name again with
+  the same extension replaces the previous directory.
+- An exporter handler gets `{ scope: 'course', courseId, title, files }` (or
+  `{ scope: 'progress' }`) and returns `{ filename, text }` or
+  `{ filename, bytes }` of at most 20 MiB. The file name has no path separator
+  and is at most 120 characters. The app asks the user where to save it.
+- A handler has 30 seconds. Throw an `Error` to refuse: its message reaches the
+  user, and nothing is written.
+
+## The tests
+
+File `test/index.test.ts` (import-export):
+
+```ts
+import { createTestServer } from '@dolphy-app/extension-sdk/testing';
+import { describe, expect, it } from 'vitest';
+import { server } from '../src/index.ts';
+
+const CSV = 'hola,hello\nadiós,goodbye\n';
+
+const start = () => createTestServer(server, { extensionId: 'acme.hello' });
+
+describe('acme.hello: importer', () => {
+  it('turns every row into a flashcard of one lesson', async () => {
+    const running = await start();
+    const { files } = await running.importer('acme.hello.import').run({
+      name: 'Spanish basics.csv',
+      text: CSV,
+    });
+    expect(Object.keys(files).sort()).toEqual([
+      'spanish-basics/cards/c1/back.md',
+      'spanish-basics/cards/c1/exercise_manifest.json',
+      'spanish-basics/cards/c1/front.md',
+      'spanish-basics/cards/c2/back.md',
+      'spanish-basics/cards/c2/exercise_manifest.json',
+      'spanish-basics/cards/c2/front.md',
+      'spanish-basics/cards/lesson_manifest.json',
+      'spanish-basics/course_manifest.json',
+    ]);
+    expect(files['spanish-basics/cards/c2/front.md']).toBe('adiós\n');
+    await running.dispose();
+  });
+
+  it('refuses a row without an answer', async () => {
+    const running = await start();
+    await expect(
+      running
+        .importer('acme.hello.import')
+        .run({ name: 'x.csv', text: 'hola\n' }),
+    ).rejects.toThrow('Row 1');
+    await running.dispose();
+  });
+});
+
+describe('acme.hello: exporter', () => {
+  it('writes the cards of the snapshot back to CSV', async () => {
+    const running = await start();
+    const result = await running.exporter('acme.hello.export').run({
+      scope: 'course',
+      courseId: 'deck',
+      title: 'Deck / Spanish',
+      files: {
+        'cards/c1/front.md': 'hola\n',
+        'cards/c1/back.md': 'hello\n',
+        'cards/c10/front.md': 'diez\n',
+        'cards/c10/back.md': 'ten\n',
+        'cards/c2/front.md': 'adiós\n',
+        'cards/c2/back.md': 'goodbye\n',
+      },
+    });
+    expect(result).toEqual({
+      filename: 'Deck - Spanish.csv',
+      text: 'hola,hello\nadiós,goodbye\ndiez,ten\n',
+    });
+    await running.dispose();
+  });
+});
+```
+
+`running.importer(id).run(input)` and `running.exporter(id).run(input)` run a
+handler with the rules of the host: the `text`/`bytes` form the importer
+declares, the `scope` the exporter declares, the size of the input and the
+shape and limits of the result. A broken result rejects with
+`invalid import result: …` / `invalid export result: …`, so the test fails the
+way the app would refuse it. For a `progress` exporter pass
+`stats: createMemoryStats(…)` to `createTestServer`.
+
+## Try and ship
+
+Run `pnpm dev`, start the app with `DOLPHY_DEV_EXTENSIONS`, open the palette and
+run "Import: Cards from CSV". After you confirm the summary the course shows up
+in Courses without a restart. See [debugging.md](debugging.md) for the rest.

package/docs/recipe-mountable.md

@@ -0,0 +1,322 @@
+# Recipe: a component of any framework
+
+The app draws a panel, an injection, an answer view or a markdown block with
+Vue, or with a `Mountable`: an object with `mount(el, ctx)` that draws into the
+element the app gives it and returns the cleanup. Nothing in a `Mountable`
+depends on Vue, so it is the base for Svelte, Solid, Lit or plain DOM. This
+recipe builds a panel on plain DOM, the smallest case, and tests it with
+`mountForTest`. React has a preset built on the same contract:
+[recipe-react.md](recipe-react.md). The command and panel basics are in
+[recipe-command-panel.md](recipe-command-panel.md); the contracts use `zod`, so
+the project lists `zod` in its `dependencies`.
+
+## The manifest
+
+File `extension.json` (mountable):
+
+```json
+{
+  "id": "acme.counter",
+  "version": "1.0.0",
+  "apiVersion": 1
+}
+```
+
+## The parts
+
+File `src/index.ts` (mountable):
+
+```ts
+export { client } from './client.ts';
+export { server } from './server.ts';
+```
+
+File `src/shared/rpc.ts` (mountable):
+
+```ts
+import { defineRpc } from '@dolphy-app/extension-sdk';
+import { z } from 'zod';
+
+export const sayHello = defineRpc({
+  name: 'greeting.say-hello',
+  input: z.object({ name: z.string() }),
+  output: z.object({ text: z.string() }),
+});
+```
+
+File `src/server.ts` (mountable):
+
+```ts
+import { defineServer } from '@dolphy-app/extension-sdk';
+import { sayHello } from './shared/rpc.ts';
+
+export const server = defineServer((s) => {
+  s.handle(sayHello, async ({ name }) => ({ text: `Hello, ${name}!` }));
+});
+```
+
+## The component
+
+File `src/hello-panel.ts` (mountable):
+
+```ts
+import { defineMountable } from '@dolphy-app/extension-sdk';
+import type { PanelHandle, PanelProps } from '@dolphy-app/extension-sdk';
+import { sayHello } from './shared/rpc.ts';
+
+// plain DOM: the element is yours, any framework mounts into it the same way
+export const HelloPanel = defineMountable<PanelProps, PanelHandle>(
+  (el, ctx) => {
+    const title = document.createElement('h2');
+    const text = document.createElement('p');
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.textContent = 'Ask the server';
+    el.append(title, text, button);
+
+    const nameOf = ({ props }: PanelProps) =>
+      typeof props === 'string' ? props : 'world';
+    const draw = (props: PanelProps) => {
+      title.textContent = `Hello, ${nameOf(props)}!`;
+    };
+    draw(ctx.props);
+    // the app opens the panel again with new properties
+    const stopProps = ctx.onProps(draw);
+
+    // the window is light or dark; the element is inside it
+    const paint = ({ dark }: { dark: boolean }) => {
+      el.dataset.dark = String(dark);
+    };
+    paint(ctx.theme);
+    const stopTheme = ctx.onTheme(paint);
+
+    // the server part answers a contract; an error is shown in place of the panel
+    const ask = () => {
+      ctx.callRpc(sayHello, { name: nameOf(ctx.props) }).then(
+        (answer) => {
+          if (!ctx.signal.aborted) text.textContent = answer.text;
+        },
+        (error: unknown) => ctx.reportError(error),
+      );
+    };
+    button.addEventListener('click', ask);
+
+    return () => {
+      stopProps();
+      stopTheme();
+      button.removeEventListener('click', ask);
+      el.replaceChildren();
+    };
+  },
+);
+```
+
+File `src/client.ts` (mountable):
+
+```ts
+import { defineClient } from '@dolphy-app/extension-sdk';
+import { HelloPanel } from './hello-panel.ts';
+
+export const client = defineClient((c) => {
+  c.addPanel({
+    id: 'acme.counter.view',
+    title: 'Hello',
+    component: HelloPanel,
+  });
+});
+```
+
+- `defineMountable<Props, Handle>(mount)` builds the object and gives it the
+  brand that `isMountable(value)` checks. `mount(el, ctx)` may return the
+  cleanup or a promise of it. The app calls the cleanup when it removes the
+  element: a route change, an extension turned off or removed, an injection
+  whose target is gone.
+- `Props` is the type of `ctx.props`: `PanelProps` (`panelId`, `props`,
+  `context`) in a panel, `InjectionProps` (`target`, `position`) in an injection,
+  `AnswerViewProps` in an answer view and `MarkdownBlockProps` (`source`,
+  `language`) in a markdown renderer. `Handle` is the type of `ctx.handle`:
+  `PanelHandle` in a panel, `InjectionHandle` in an injection and `undefined`
+  elsewhere.
+- The same component fits `client.addPanel`, `client.addInjection`,
+  `client.addAnswerView` and `client.addMarkdownRenderer` as its `component`,
+  where a Vue component fits.
+
+## The context
+
+`ctx` (`MountContext`) is everything a Vue component gets from `usePanel`,
+`useApp`, `useEngine` and `useRpc`, without Vue:
+
+| Field                   | What it is                                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------------------------ |
+| `props`, `onProps(fn)`  | The current props, a snapshot that is never changed in place, and a listener for the next one.          |
+| `theme`, `onTheme(fn)`  | `{ id, dark }` of the window and a listener for a change.                                              |
+| `locale`, `onLocale(fn)` | `'en'` or `'ru'` and a listener for a change.                                                        |
+| `emit(event, payload?)` | Sends an event to the app. Only an answer view has events (see below); elsewhere it does nothing.       |
+| `app`, `engine`         | The window API (`AppApi`) and the engine client, the same objects as `client.app` and `client.engine`. |
+| `callRpc(contract, input)` | Calls the server part: validates the input and the answer with the contract; a failure rejects.      |
+| `extensionId`           | The id of this extension.                                                                              |
+| `signal`                | An `AbortSignal` aborted when the element is removed: pass it to `fetch`, check it after an `await`.  |
+| `reportError(error)`    | Shows the card "Extension <name>: <error>" with a "Retry" button in place of the component.            |
+| `handle`                | The panel handle (`panelId`, `props`, `context`, `call(commandId, args?)`) or the injection handle.    |
+
+Every `on…` returns the function that stops listening; call it in the cleanup.
+An exception that `mount` throws is reported the same way as `reportError`.
+
+An answer view tells the app about the answer with `emit`:
+
+<!-- fragment -->
+
+```ts
+import { defineMountable } from '@dolphy-app/extension-sdk';
+import type { AnswerChange, AnswerViewProps } from '@dolphy-app/extension-api';
+
+export const Choice = defineMountable<AnswerViewProps<string[], string>>(
+  (el, ctx) => {
+    const select = document.createElement('select');
+    select.append(...ctx.props.view.map((option) => new Option(option)));
+    select.disabled = ctx.props.disabled;
+    select.addEventListener('change', () => {
+      const change: AnswerChange<string> = {
+        value: select.value,
+        complete: true,
+      };
+      ctx.emit('change', change);
+    });
+    el.append(select);
+    return () => el.replaceChildren();
+  },
+);
+```
+
+`emit('change', { value, complete })` reports the current answer and
+`emit('submit')` asks the app to check it.
+
+## The tests
+
+File `test/index.test.ts` (mountable):
+
+```ts
+// @vitest-environment happy-dom
+import { isMountable } from '@dolphy-app/extension-sdk';
+import type { ExtensionEngine, PanelProps } from '@dolphy-app/extension-sdk';
+import {
+  createTestClient,
+  createTestServer,
+  mountForTest,
+} from '@dolphy-app/extension-sdk/testing';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { client, server } from '../src/index.ts';
+import { HelloPanel } from '../src/hello-panel.ts';
+import { sayHello } from '../src/shared/rpc.ts';
+
+const disposables: { dispose(): unknown }[] = [];
+afterEach(async () => {
+  await Promise.all(disposables.splice(0).map((item) => item.dispose()));
+});
+
+describe('acme.counter: server', () => {
+  it('answers the contract', async () => {
+    const running = await createTestServer(server, {
+      extensionId: 'acme.counter',
+    });
+    disposables.push(running);
+    expect(await running.rpc(sayHello, { name: 'Ada' })).toEqual({
+      text: 'Hello, Ada!',
+    });
+  });
+});
+
+describe('acme.counter: client', () => {
+  it('adds the panel as a mountable', async () => {
+    const running = await createTestClient(client, {
+      extensionId: 'acme.counter',
+    });
+    disposables.push(running);
+    expect(running.panels.map((panel) => panel.id)).toEqual([
+      'acme.counter.view',
+    ]);
+    expect(isMountable(running.panels[0]?.component)).toBe(true);
+  });
+});
+
+const panelProps = (props: PanelProps['props']): PanelProps => ({
+  panelId: 'acme.counter.view',
+  props,
+  context: { courseId: null },
+});
+
+// the engine of the window: `ctx.callRpc` goes through `extensions.invokeRpc`
+const engineAnswering = (
+  answer: (request: { name: string; input: unknown }) => Promise<unknown>,
+) => ({ extensions: { invokeRpc: answer } }) as unknown as ExtensionEngine;
+
+const mountPanel = async (
+  props: PanelProps['props'],
+  engine: ExtensionEngine,
+) => {
+  const mounted = await mountForTest(HelloPanel, {
+    props: panelProps(props),
+    handle: { ...panelProps(props), call: async () => undefined },
+    engine,
+    extensionId: 'acme.counter',
+  });
+  disposables.push({ dispose: () => mounted.unmount() });
+  return mounted;
+};
+
+describe('acme.counter: panel', () => {
+  it('greets, follows the props and the theme, asks the server', async () => {
+    const asked: unknown[] = [];
+    const mounted = await mountPanel(
+      'Ada',
+      engineAnswering(async (request) => {
+        asked.push(request.input);
+        return { text: 'Hello from the server' };
+      }),
+    );
+    expect(mounted.el.querySelector('h2')?.textContent).toBe('Hello, Ada!');
+    expect(mounted.el.dataset.dark).toBe('false');
+
+    mounted.setProps(panelProps('Grace'));
+    mounted.setTheme({ id: 'night', dark: true });
+    expect(mounted.el.querySelector('h2')?.textContent).toBe('Hello, Grace!');
+    expect(mounted.el.dataset.dark).toBe('true');
+
+    mounted.el.querySelector('button')?.click();
+    await vi.waitFor(() =>
+      expect(mounted.el.querySelector('p')?.textContent).toBe(
+        'Hello from the server',
+      ),
+    );
+    expect(asked).toEqual([{ name: 'Grace' }]);
+  });
+
+  it('reports a failed call and cleans up on unmount', async () => {
+    const mounted = await mountPanel(
+      undefined,
+      engineAnswering(async () => {
+        throw new Error('server is down');
+      }),
+    );
+    mounted.el.querySelector('button')?.click();
+    await vi.waitFor(() => expect(mounted.errors).toHaveLength(1));
+
+    await mounted.unmount();
+    expect(mounted.ctx.signal.aborted).toBe(true);
+    expect(mounted.el.childElementCount).toBe(0);
+  });
+});
+```
+
+`mountForTest(mountable, { props, handle, engine, … })` mounts the component
+into a new `<div>` on a context the test controls. `setProps`, `setTheme` and
+`setLocale` change the context and call the `on…` listeners; `emitted` lists
+the `ctx.emit` calls as `[event, payload]`, `errors` the `ctx.reportError`
+calls; `unmount()` aborts `ctx.signal` and runs the cleanup. Without `app` and
+`engine` any use of them throws, so pass the ones the component touches. The
+`engine` is also what `ctx.callRpc` talks to, as `useRpc` does in a window.
+
+## Try and ship
+
+Run `pnpm dev`, start the app with `DOLPHY_DEV_EXTENSIONS` and open the "Hello"
+panel from the sidebar menu.