@dolphy-app/extension-sdk 0.3.0 → 0.5.0

package/docs/recipe-rpc-and-app.md

@@ -0,0 +1,366 @@
+# Recipe: calls between the parts, the engine and the window
+
+A component of the client part can ask the server part for something, call the
+engine itself and drive the window: open a course, show a toast, mount a
+component into an element. This recipe builds a panel that lists the courses
+and records an attempt, with `defineRpc`, `useRpc`, `useEngine`, `useApp` and
+`server.engine`. There is no template for it; add the pieces to any project
+(see [quick-start.md](quick-start.md)). The contracts use `zod`, so the project
+lists `zod` in its `dependencies`; the build puts it into the bundles. The
+command and panel basics are in [recipe-command-panel.md](recipe-command-panel.md).
+
+## The manifest
+
+File `extension.json` (rpc-and-app):
+
+```json
+{
+  "id": "acme.direct",
+  "version": "1.0.0",
+  "apiVersion": 1
+}
+```
+
+## The contracts
+
+File `src/index.ts` (rpc-and-app):
+
+```ts
+export { client } from './client.ts';
+export { server } from './server.ts';
+```
+
+File `src/shared/rpc.ts` (rpc-and-app):
+
+```ts
+import { defineRpc } from '@dolphy-app/extension-sdk';
+import { z } from 'zod';
+
+// imported by both parts: the name and the schemas of a call
+export const courseNames = defineRpc({
+  name: 'courses.names',
+  input: z.object({}),
+  output: z.object({ names: z.array(z.string()) }),
+});
+
+export const markKnown = defineRpc({
+  name: 'attempts.mark-known',
+  input: z.object({ exerciseId: z.string().min(1) }),
+  output: z.object({ eventId: z.string() }),
+});
+```
+
+- `defineRpc({ name, input, output })` returns the contract as is. `name` is
+  lower-case segments separated by dots, at least two, up to 120 characters
+  (`greeting.say-hello`); a malformed name throws. `input` and `output` are
+  `zod` schemas. `defineRpc` does not import `vue`, so server code imports it
+  too (it is also exported from `@dolphy-app/extension-sdk/rpc`).
+- Both sides validate: `useRpc` checks the input before the call and the
+  answer after it, the server checks the input before the handler and the
+  result after it. The data crosses the process boundary as JSON, so keep it
+  plain values (at most 200 000 characters of input).
+
+## The server part
+
+File `src/server.ts` (rpc-and-app):
+
+```ts
+import { defineServer } from '@dolphy-app/extension-sdk';
+import { courseNames, markKnown } from './shared/rpc.ts';
+
+export const server = defineServer((s) => {
+  s.handle(courseNames, async () => {
+    const page = await s.engine.library.listCourses();
+    return { names: page.items.map((course) => course.name) };
+  });
+
+  s.handle(markKnown, async ({ exerciseId }) => {
+    const result = await s.engine.practice.recordAttempt({
+      requestId: crypto.randomUUID(),
+      exerciseId,
+      grade: 5,
+    });
+    return { eventId: result.eventId };
+  });
+});
+```
+
+- `server.handle(contract, handler)` answers a contract: one handler per name,
+  at most 64 per extension. The handler has 10 seconds. An error it throws
+  reaches the component with its message.
+- `server.engine` is the engine client (`ExtensionEngine`): every method of the
+  engine contract, writing ones included, and `subscribe` for the engine
+  events, but not `close`. A write goes into the same log as the window's own
+  writes, so record only what the learner really did.
+
+## The client part
+
+File `src/client.ts` (rpc-and-app):
+
+```ts
+import { defineClient } from '@dolphy-app/extension-sdk';
+import { Panel } from './panel.ts';
+
+export const client = defineClient((c) => {
+  c.addPanel({
+    id: 'acme.direct.view',
+    title: { en: 'Direct', ru: 'Прямой доступ' },
+    component: Panel,
+  });
+});
+```
+
+File `src/panel.ts` (rpc-and-app):
+
+```ts
+import { useApp, useEngine, useRpc } from '@dolphy-app/extension-sdk/client';
+import { defineComponent, h, ref } from 'vue';
+import { courseNames, markKnown } from './shared/rpc.ts';
+
+export const Panel = defineComponent({
+  setup() {
+    const app = useApp();
+    const engine = useEngine();
+    const loadNames = useRpc(courseNames);
+    const mark = useRpc(markKnown);
+    const names = ref<string[]>([]);
+
+    const report = (error: unknown) =>
+      app.notify(
+        error instanceof Error ? error.message : String(error),
+        'error',
+      );
+
+    // through the server part: `courses.names`
+    const loadFromServer = async () => {
+      try {
+        names.value = (await loadNames({})).names;
+      } catch (error) {
+        report(error);
+      }
+    };
+
+    // straight from the component: the same engine client
+    const loadHere = async () => {
+      try {
+        const page = await engine.library.listCourses();
+        names.value = page.items.map((course) => course.name);
+      } catch (error) {
+        report(error);
+      }
+    };
+
+    const markExercise = async (exerciseId: string) => {
+      try {
+        await mark({ exerciseId });
+        app.notify('Recorded');
+      } catch (error) {
+        report(error);
+      }
+    };
+
+    return () =>
+      h('div', [
+        h(
+          'button',
+          { 'data-role': 'server', onClick: loadFromServer },
+          'Server',
+        ),
+        h('button', { 'data-role': 'here', onClick: loadHere }, 'Here'),
+        h(
+          'button',
+          { 'data-role': 'mark', onClick: () => markExercise('') },
+          'Mark with an empty id',
+        ),
+        h(
+          'ul',
+          names.value.map((name) => h('li', name)),
+        ),
+      ]);
+  },
+});
+```
+
+- `useRpc(contract)` is called in `setup` and returns `(input) => Promise<output>`.
+  A schema violation, an error of the handler and an unavailable server reject
+  the promise with an `Error` that carries the message.
+- `useEngine()` is the client of the window itself: `engine.library`,
+  `engine.practice`, `engine.settings`, … and `engine.subscribe`.
+- `useApp()` is a fixed list of window capabilities: `openCourse(courseId)`,
+  `openLesson(courseId, lessonId)`, `openExercise(courseId, lessonId, exerciseId)`,
+  `openPanel(extensionId, panelId, props?)`, `openSettings(extensionId?)`,
+  `notify(message, kind?)`, the reactive `theme` (`{ id, dark }`) and `locale`
+  (`'en' | 'ru'`), `runCommand(commandKey)` for a palette command
+  (`extension:<extension id>:<command id>`) and `mountAt(target, component,
+props?)`. The window's stores and router are not reachable.
+- `app.mountAt('#some-element', Component, props)` mounts a component into an
+  element of the window (a CSS selector is resolved once, at the call; a
+  missing element throws) and returns a `Disposable`. The component gets
+  Vuetify, the theme, `useApp()`, `useEngine()` and `useRpc()` like a panel.
+  For a component that follows the DOM, use `client.addInjection`.
+- All three work only in a component the app draws; elsewhere they throw.
+
+## The tests
+
+File `test/index.test.ts` (rpc-and-app):
+
+```ts
+// @vitest-environment happy-dom
+import {
+  APP_KEY,
+  ENGINE_KEY,
+  EXTENSION_ID_KEY,
+} from '@dolphy-app/extension-sdk';
+import type { AppApi, ExtensionEngine } from '@dolphy-app/extension-sdk';
+import {
+  createTestClient,
+  createTestServer,
+} from '@dolphy-app/extension-sdk/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+import { createApp, h, nextTick } from 'vue';
+import { client, server } from '../src/index.ts';
+import { Panel } from '../src/panel.ts';
+import { courseNames, markKnown } from '../src/shared/rpc.ts';
+
+const disposables: { dispose(): unknown }[] = [];
+afterEach(async () => {
+  await Promise.all(disposables.splice(0).map((item) => item.dispose()));
+});
+
+// only the methods the code under test calls
+const recorded: unknown[] = [];
+const engine = {
+  library: {
+    listCourses: async () => ({ items: [{ name: 'Git' }, { name: 'SQL' }] }),
+  },
+  practice: {
+    recordAttempt: async (request: unknown) => {
+      recorded.push(request);
+      return { eventId: 'event-1' };
+    },
+  },
+} as unknown as ExtensionEngine;
+
+describe('acme.direct: server', () => {
+  it('answers the contracts through the engine', async () => {
+    const running = await createTestServer(server, {
+      extensionId: 'acme.direct',
+      engine,
+    });
+    disposables.push(running);
+    expect(running.registration.rpcs).toEqual([
+      'courses.names',
+      'attempts.mark-known',
+    ]);
+    expect(await running.rpc(courseNames, {})).toEqual({
+      names: ['Git', 'SQL'],
+    });
+    expect(await running.rpc(markKnown, { exerciseId: 'git::a::q1' })).toEqual({
+      eventId: 'event-1',
+    });
+    expect(recorded).toMatchObject([{ exerciseId: 'git::a::q1', grade: 5 }]);
+  });
+
+  it('rejects an input that breaks the contract before the handler runs', async () => {
+    const running = await createTestServer(server, {
+      extensionId: 'acme.direct',
+      engine,
+    });
+    disposables.push(running);
+    const before = recorded.length;
+    await expect(running.rpc(markKnown, { exerciseId: '' })).rejects.toThrow();
+    expect(recorded).toHaveLength(before);
+  });
+});
+
+describe('acme.direct: client', () => {
+  it('adds the panel', async () => {
+    const running = await createTestClient(client, {
+      extensionId: 'acme.direct',
+    });
+    disposables.push(running);
+    expect(running.panels.map((panel) => panel.id)).toEqual([
+      'acme.direct.view',
+    ]);
+  });
+});
+
+// draws the panel the way the app does: the keys are provided to the component
+const mountPanel = (invoked: string[], toasts: string[]) => {
+  const app = {
+    notify: (message: string, kind?: string) =>
+      toasts.push(`${kind ?? 'info'}: ${message}`),
+  } as unknown as AppApi;
+  const windowEngine = {
+    ...engine,
+    extensions: {
+      invokeRpc: async (request: { name: string }) => {
+        invoked.push(request.name);
+        return { names: ['From the server'] };
+      },
+    },
+  } as unknown as ExtensionEngine;
+  const host = document.createElement('div');
+  document.body.append(host);
+  const root = createApp({ render: () => h(Panel) });
+  root.provide(EXTENSION_ID_KEY, 'acme.direct');
+  root.provide(APP_KEY, app);
+  root.provide(ENGINE_KEY, windowEngine);
+  root.mount(host);
+  disposables.push({
+    dispose: () => {
+      root.unmount();
+      host.remove();
+    },
+  });
+  return host;
+};
+
+const click = async (host: HTMLElement, role: string) => {
+  host.querySelector<HTMLButtonElement>(`[data-role="${role}"]`)?.click();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await nextTick();
+};
+
+describe('acme.direct: panel', () => {
+  it('lists the courses through the server and straight from the engine', async () => {
+    const invoked: string[] = [];
+    const host = mountPanel(invoked, []);
+    await click(host, 'server');
+    expect(invoked).toEqual(['courses.names']);
+    expect(host.querySelector('li')?.textContent).toBe('From the server');
+
+    await click(host, 'here');
+    expect(
+      [...host.querySelectorAll('li')].map((li) => li.textContent),
+    ).toEqual(['Git', 'SQL']);
+  });
+
+  it('shows a rejected call as an error toast and does not reach the server', async () => {
+    const invoked: string[] = [];
+    const toasts: string[] = [];
+    const host = mountPanel(invoked, toasts);
+    await click(host, 'mark');
+    expect(invoked).toEqual([]);
+    expect(toasts).toHaveLength(1);
+    expect(toasts[0]).toMatch(/^error: /);
+  });
+});
+```
+
+`createTestServer(server, { extensionId, engine })` gives the code the engine
+you pass as `s.engine`; without it any use of `s.engine` throws. `running.rpc(contract, input)`
+calls the handler the way the host does: the input must pass the contract's
+schema and so must the result; an unregistered name and an error of the handler
+reject the promise. `running.registration.rpcs` lists the names.
+
+A component that uses `useRpc`, `useApp` or `useEngine` is mounted like any Vue
+component in `happy-dom`: `app.provide(EXTENSION_ID_KEY, id)`,
+`app.provide(APP_KEY, appApi)` and `app.provide(ENGINE_KEY, engine)` give it
+what the app would. `createTestClient(client, { extensionId, app, engine })`
+passes `app` and `engine` to the entry as `client.app` and `client.engine`.
+
+## Try and ship
+
+Run `pnpm dev`, start the app with `DOLPHY_DEV_EXTENSIONS` and open the "Direct"
+panel from the sidebar menu.

package/docs/recipe-settings.md

@@ -0,0 +1,183 @@
+# Recipe: settings
+
+Let the user configure the extension in Settings → Extensions. The code
+registers the definitions; the app draws the form, validates the values and
+stores them; your code reads them. 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` (settings):
+
+```json
+{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
+  "id": "acme.hello",
+  "version": "0.1.0",
+  "apiVersion": 1,
+  "name": "Hello settings",
+  "description": "A greeting command whose text follows the user's settings.",
+  "author": "your-github-login",
+  "tags": ["productivity"]
+}
+```
+
+The manifest holds the identity only; the settings are registered by the code.
+
+## The code
+
+File `src/index.ts` (settings):
+
+```ts
+import { defineServer, notify } from '@dolphy-app/extension-sdk';
+
+export const server = defineServer((s) => {
+  s.registerSettings([
+    {
+      id: 'acme.hello.name',
+      type: 'string',
+      label: { en: 'Name to greet', ru: 'Кого приветствовать' },
+      default: 'world',
+      maxLength: 40,
+    },
+    {
+      id: 'acme.hello.times',
+      type: 'number',
+      label: { en: 'Exclamation marks', ru: 'Восклицательные знаки' },
+      default: 1,
+      min: 1,
+      max: 5,
+      integer: true,
+    },
+    {
+      id: 'acme.hello.style',
+      type: 'enum',
+      label: { en: 'Style', ru: 'Стиль' },
+      default: 'plain',
+      options: [
+        { value: 'plain', label: { en: 'Plain', ru: 'Обычный' } },
+        { value: 'loud', label: { en: 'Loud', ru: 'Громкий' } },
+      ],
+    },
+  ]);
+
+  s.registerCommand({
+    id: 'acme.hello.greet',
+    title: { en: 'Greet', ru: 'Поприветствовать' },
+    run: () => {
+      // `get` is synchronous and returns the user's value or the default
+      const name = String(s.settings.get('acme.hello.name'));
+      const marks = '!'.repeat(Number(s.settings.get('acme.hello.times')));
+      const text = `Hello, ${name}${marks}`;
+      return notify(
+        s.settings.get('acme.hello.style') === 'loud'
+          ? text.toUpperCase()
+          : text,
+      );
+    },
+  });
+
+  // a change in Settings → Extensions reaches the running extension
+  s.settings.onDidChange((change) => {
+    s.logger.info({ id: change.id, value: change.value }, 'setting changed');
+  });
+});
+```
+
+- `server.registerSettings(definitions)` adds the settings to Settings →
+  Extensions. Types: `boolean`, `string` (`maxLength`), `text` (a multi-line
+  string), `color` (`#rrggbb`), `list` (`maxItems`, `itemMaxLength`), `number`
+  (`min`, `max`, `integer`) and `enum` (`options: [{ value, label }]`).
+- A setting `id` is the extension id or starts with `<id>.`, and is registered
+  once. `default` must satisfy the constraints, otherwise the registration
+  fails and the extension shows `load-failed`.
+- `label`, `description` and `group` are `LocalizedText`: a string, or
+  `{ en, ru }` as here. `order` sorts the form; `visibleWhen: { setting, equals }`
+  hides a field while another setting of the extension has a different value.
+- `server.settings.get(id)` returns the user's value or the default (an id
+  nobody registered throws) as a `SettingValue`; narrow it where you use it,
+  as `String(…)` and `Number(…)` do here. Read a value where you use it. Cache
+  it only if you also subscribe with `onDidChange`.
+- The app validates every value (type, range, integer, length, `options`)
+  before it reaches you, so the code needs no checks of its own.
+
+## The test
+
+File `test/index.test.ts` (settings):
+
+```ts
+import { createTestServer } from '@dolphy-app/extension-sdk/testing';
+import { expect, it } from 'vitest';
+import { server } from '../src/index.ts';
+
+const start = (settingValues = {}) =>
+  createTestServer(server, { extensionId: 'acme.hello', settingValues });
+
+it('the greeting follows the settings, also after a change', async () => {
+  const running = await start();
+  expect(await running.commands.run('acme.hello.greet')).toEqual({
+    kind: 'notify',
+    text: 'Hello, world!',
+  });
+
+  await running.settings.set('acme.hello.name', 'Ada');
+  await running.settings.set('acme.hello.times', 3);
+  await running.settings.set('acme.hello.style', 'loud');
+  expect(await running.commands.run('acme.hello.greet')).toEqual({
+    kind: 'notify',
+    text: 'HELLO, ADA!!!',
+  });
+  await running.dispose();
+});
+
+it('a user value of a setting replaces the default', async () => {
+  const running = await start({ 'acme.hello.name': 'Grace' });
+  expect(await running.commands.run('acme.hello.greet')).toMatchObject({
+    text: 'Hello, Grace!',
+  });
+  await running.dispose();
+});
+
+it('the test settings reject a value the app would reject', async () => {
+  const running = await start();
+  await expect(running.settings.set('acme.hello.times', 9)).rejects.toThrow(
+    'acme.hello.times',
+  );
+  await expect(
+    running.settings.set('acme.hello.style', 'quiet'),
+  ).rejects.toThrow('acme.hello.style');
+  await running.dispose();
+});
+
+it('a change is logged', async () => {
+  const logged: object[] = [];
+  const logger = {
+    debug: () => undefined,
+    info: (fields: object) => void logged.push(fields),
+    warn: () => undefined,
+    error: () => undefined,
+  };
+  const running = await createTestServer(server, {
+    extensionId: 'acme.hello',
+    logger,
+  });
+  await running.settings.set('acme.hello.name', 'Ada');
+  expect(logged).toEqual([{ id: 'acme.hello.name', value: 'Ada' }]);
+  await running.dispose();
+});
+```
+
+`createTestServer` starts `server` with the settings in memory:
+`running.settings.get` returns the default until a value is set, and
+`running.settings.set(id, value)` checks the value against the definition the
+way the app does and calls the `onDidChange` subscribers, so the test changes a
+value as the user does in the dialog. `settingValues` starts the extension with
+user values in place of the defaults; every id must be registered by `server`.
+The `logger` option receives what `server.logger` is called with.
+
+## Try and ship
+
+Run `pnpm dev`, start the app with `DOLPHY_DEV_EXTENSIONS`, open Settings →
+Extensions, press "Settings" on the extension, change a value and run "Greet"
+from the palette.

package/docs/recipe-theme.md

@@ -0,0 +1,148 @@
+# Recipe: a theme
+
+A theme is data that the client part registers: no server part, no `main.mjs`.
+This recipe is the `theme` template
+(`npx @dolphy-app/create-extension <dir> --id acme.hello --template theme`).
+The files below are exactly what the generator writes for the id `acme.hello`.
+See [quick-start.md](quick-start.md) for the commands.
+
+## The manifest
+
+File `extension.json` (theme):
+
+```json
+{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
+  "id": "acme.hello",
+  "version": "0.1.0",
+  "apiVersion": 1,
+  "name": "Midnight",
+  "description": "A dark color theme with an amber accent for the Dolphy app.",
+  "author": "your-github-login",
+  "tags": ["theme"]
+}
+```
+
+The manifest holds the identity only; the colors are in the code.
+
+## The code
+
+File `src/theme.ts` (theme):
+
+```ts
+import type { ThemeRegistration } from '@dolphy-app/extension-sdk';
+
+// the allowed color and variable keys are `THEME_COLOR_KEYS` and
+// `THEME_VARIABLE_KEYS` of '@dolphy-app/extension-sdk'
+export const midnight: ThemeRegistration = {
+  id: 'acme.hello',
+  label: 'Midnight',
+  dark: true,
+  colors: {
+    background: '#101820',
+    surface: '#1B2733',
+    'on-background': '#E6EDF3',
+    'on-surface': '#E6EDF3',
+    primary: '#FFB000',
+    'on-primary': '#101820',
+  },
+  variables: { 'border-opacity': 0.2 },
+};
+```
+
+File `src/index.ts` (theme):
+
+```ts
+import { defineClient } from '@dolphy-app/extension-sdk';
+import { midnight } from './theme.ts';
+
+// runs in the app window: a theme is data, there is no server part
+export const client = defineClient((c) => {
+  c.addTheme(midnight);
+});
+```
+
+- `client.addTheme(registration)` adds a tile to Settings → Appearance next to
+  System, Light and Dark. `id` is the extension id or starts with it and a dot,
+  and is not `system`, `light` or `dark`; `label` is a `LocalizedText` of 1–60
+  characters; `dark` says whether the theme is dark, which picks the base colors
+  of the interface that `colors` then override.
+- `colors` are `#rrggbb` or `#rrggbbaa` values for a fixed list of roles
+  (`background`, `surface`, `primary`, the `on-…` colors for text drawn on them,
+  `error`, `success`…). The list is `THEME_COLOR_KEYS` of the SDK; a key outside
+  it fails the registration. Pair every background with a readable text color.
+- `variables` are optional tokens from `THEME_VARIABLE_KEYS`; here
+  `border-opacity`, a number from 0 to 1.
+- The build of this project writes `extension.json` and `client.mjs` to
+  `dist-ext`: there is no `server` export, so no `main.mjs`.
+
+## The test
+
+File `test/theme.test.ts` (theme):
+
+```ts
+import { createTestClient } from '@dolphy-app/extension-sdk/testing';
+import { describe, expect, it } from 'vitest';
+import { client } from '../src/index.ts';
+import { midnight } from '../src/theme.ts';
+
+const colors = midnight.colors;
+
+// WCAG relative luminance of a #rrggbb color
+const luminance = (hex: string): number => {
+  const [r, g, b] = [1, 3, 5].map((start) => {
+    const channel = Number.parseInt(hex.slice(start, start + 2), 16) / 255;
+    return channel <= 0.03928 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+  }) as [number, number, number];
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+
+const contrast = (foreground: string, background: string): number => {
+  const [light, dark] = [luminance(foreground), luminance(background)].sort(
+    (a, b) => b - a,
+  ) as [number, number];
+  return (light + 0.05) / (dark + 0.05);
+};
+
+describe('acme.hello: theme', () => {
+  it('the client adds the theme', async () => {
+    const running = await createTestClient(client, { extensionId: 'acme.hello' });
+    expect(running.themes).toEqual([midnight]);
+    await running.dispose();
+  });
+
+  it.each([
+    ['on-surface', 'surface'],
+    ['on-background', 'background'],
+    ['on-primary', 'primary'],
+  ])('%s on %s has a contrast of at least 4.5:1', (foreground, background) => {
+    expect(contrast(colors[foreground] as string, colors[background] as string))
+      .toBeGreaterThanOrEqual(4.5);
+  });
+
+  it('a dark theme has a dark background and a light text', () => {
+    const background = luminance(colors['background'] as string);
+    const text = luminance(colors['on-background'] as string);
+    expect(midnight.dark ? background < text : background > text).toBe(true);
+  });
+});
+```
+
+`createTestClient(client, { extensionId })` runs `client` on a context that
+records what it adds, so the test sees the theme in `running.themes`. The rest
+checks the WCAG contrast of each text color against its background (at least
+4.5:1) and that `dark` agrees with the colors. A failing contrast is a real bug
+the learner would see. Keep the test when you change the colors.
+
+## Try and ship
+
+```sh
+pnpm install
+pnpm test
+pnpm dev
+```
+
+With `DOLPHY_DEV_EXTENSIONS` pointing at `dist-ext` (see the quick start) the
+theme appears as a tile in Settings → Appearance; saving a file is picked up by
+the running app. Change the id, the label and the colors; change `tags` and
+`description` too, the catalog shows them.