@dolphy-app/extension-sdk 0.3.0 → 0.4.0

package/docs/recipe-settings.md

@@ -0,0 +1,161 @@
+# Recipe: settings
+
+Let the user configure the extension in Settings → Extensions. The app draws the
+form from the definitions in the manifest, 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"],
+  "contributes": {
+    "commands": [{ "id": "acme.hello.greet", "title": "Greet" }],
+    "settings": [
+      {
+        "id": "acme.hello.name",
+        "type": "string",
+        "label": "Name to greet",
+        "default": "world",
+        "maxLength": 40
+      },
+      {
+        "id": "acme.hello.times",
+        "type": "number",
+        "label": "Exclamation marks",
+        "default": 1,
+        "min": 1,
+        "max": 5,
+        "integer": true
+      },
+      {
+        "id": "acme.hello.style",
+        "type": "enum",
+        "label": "Style",
+        "default": "plain",
+        "options": [
+          { "value": "plain", "label": "Plain" },
+          { "value": "loud", "label": "Loud" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+- Types: `boolean`, `string` (`maxLength`), `number` (`min`, `max`, `integer`)
+  and `enum` (`options: [{ value, label }]`).
+- A setting `id` is the extension id or starts with `<id>.`. `default` must
+  satisfy the constraints, otherwise the manifest is rejected.
+- `label` (1–60 characters) and `description` (up to 500) are shown as written;
+  they are data of the extension and are not translated.
+
+## The code
+
+File `src/index.ts` (settings):
+
+```ts
+import {
+  defineExtension,
+  inActivate,
+  notify,
+} from '@dolphy-app/extension-sdk';
+
+export const host = defineExtension({
+  commands: { 'acme.hello.greet': inActivate },
+  activate(ctx) {
+    ctx.commands.register('acme.hello.greet', () => {
+      // `get` is synchronous and returns the user's value or the default
+      const name = ctx.settings.get('acme.hello.name');
+      const marks = '!'.repeat(ctx.settings.get('acme.hello.times'));
+      const style = ctx.settings.get('acme.hello.style');
+      const text = `Hello, ${name}${marks}`;
+      return notify(style === 'loud' ? text.toUpperCase() : text);
+    });
+
+    // a change in Settings → Extensions reaches the running extension
+    ctx.settings.onDidChange((change) => {
+      ctx.logger.info({ id: change.id, value: change.value }, 'setting changed');
+    });
+  },
+});
+```
+
+- The ids are typed from the manifest: `ctx.settings.get('acme.hello.times')` is
+  a `number`, `style` is `'plain' | 'loud'`, an undeclared id does not compile.
+- Read a value where you use it. Cache it only if you also subscribe with
+  `onDidChange`, as the `exercise` template does.
+- The engine 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 type { SettingContribution } from '@dolphy-app/extension-sdk';
+import {
+  createMemorySettings,
+  loadCommands,
+} from '@dolphy-app/extension-sdk/testing';
+import { expect, it } from 'vitest';
+import manifest from '../extension.json';
+import { host } from '../src/index.ts';
+
+const definitions = manifest.contributes.settings as SettingContribution[];
+
+it('the greeting follows the settings, also after a change', async () => {
+  const settings = createMemorySettings(definitions);
+  const commands = await loadCommands(host, {
+    settings,
+    declaredCommands: ['acme.hello.greet'],
+  });
+
+  expect(await commands.run('acme.hello.greet')).toEqual({
+    kind: 'notify',
+    text: 'Hello, world!',
+  });
+
+  await settings.set('acme.hello.name', 'Ada');
+  await settings.set('acme.hello.times', 3);
+  await settings.set('acme.hello.style', 'loud');
+  expect(await commands.run('acme.hello.greet')).toEqual({
+    kind: 'notify',
+    text: 'HELLO, ADA!!!',
+  });
+  await commands.dispose();
+});
+
+it('the memory settings reject a value the engine would reject', async () => {
+  const settings = createMemorySettings(definitions);
+  await expect(settings.set('acme.hello.times', 9)).rejects.toThrow(
+    'acme.hello.times',
+  );
+  await expect(settings.set('acme.hello.style', 'quiet')).rejects.toThrow(
+    'acme.hello.style',
+  );
+});
+```
+
+`createMemorySettings(definitions, values?)` is the settings the host gives
+`ctx`: `get` returns the default until a value is set, `set(id, value)` checks
+the value against the definition and calls the `onDidChange` subscribers. Pass
+it to `loadCommands` (or `loadEvents`, `loadExerciseType`) through `settings`.
+`loadEvents` takes the definitions and `settingValues` directly.
+
+## 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,116 @@
+# Recipe: a theme
+
+A theme is data: no TypeScript, 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"],
+  "contributes": {
+    "themes": [
+      {
+        "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 }
+      }
+    ]
+  }
+}
+```
+
+- `contributes.themes[]` has an `id` (not `system`, `light` or `dark`), a
+  `label` of 1–60 characters and `dark`, which says whether the theme is dark
+  and so 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`…). A key outside the list is rejected by `pnpm validate`.
+  Pair every background with a readable text color.
+- `variables` are optional tokens from a fixed list; here `border-opacity`, a
+  number from 0 to 1.
+- `build` of a project with no code writes only `extension.json` to `dist-ext`.
+
+## The test
+
+File `test/theme.test.ts` (theme):
+
+```ts
+import { describe, expect, it } from 'vitest';
+import manifest from '../extension.json';
+
+const [theme] = manifest.contributes.themes;
+const colors: Record<string, string> = theme.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.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(theme.dark ? background < text : background > text).toBe(true);
+  });
+});
+```
+
+A project with no code still has something worth testing. The test reads the
+manifest and 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, and the test also gives `vitest run` a file to
+run. 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 next to System, Light and
+Dark; saving `extension.json` is picked up by the running app. Change the id, the label and the colors; change `tags` and
+`description` too, the catalog shows them.

package/docs/recipe-ui-kit.md

@@ -0,0 +1,172 @@
+# Recipe: a panel on the UI kit
+
+`@dolphy-app/extension-ui` gives a panel ready, accessible elements, so you do
+not write markup, keyboard handling or dark-theme colours yourself. This recipe
+has no template of its own: start from `blank`, install the kit
+(`pnpm add @dolphy-app/extension-ui`) 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` (ui-kit):
+
+```json
+{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
+  "id": "acme.hello",
+  "version": "0.1.0",
+  "apiVersion": 1,
+  "name": "Hello notes",
+  "description": "A panel with a text field, a button and a list built on the UI kit.",
+  "author": "your-github-login",
+  "tags": ["productivity"],
+  "contributes": {
+    "panels": [{ "id": "acme.hello.view", "title": "Notes" }]
+  }
+}
+```
+
+## The code
+
+File `src/index.ts` (ui-kit):
+
+```ts
+import { defineExtensionPanel } from '@dolphy-app/extension-sdk';
+import type { ExtensionPanels } from '@dolphy-app/extension-sdk';
+import {
+  button,
+  card,
+  emptyState,
+  list,
+  textField,
+} from '@dolphy-app/extension-ui';
+
+export const panels = {
+  'acme.hello.view': defineExtensionPanel({
+    mount(container) {
+      const notes: string[] = [];
+      let draft = '';
+      const status = document.createElement('p');
+      status.setAttribute('role', 'status');
+      const body = document.createElement('div');
+      // elements are static: draw the list again with replaceChildren
+      const render = () => {
+        body.replaceChildren(
+          notes.length === 0
+            ? emptyState({
+                title: 'No notes yet',
+                description: 'Type a note and press Add.',
+              })
+            : list({
+                label: 'Notes',
+                emptyText: 'No notes',
+                items: notes.map((note, index) => ({
+                  id: String(index),
+                  label: note,
+                })),
+                onSelect: (id) => {
+                  status.textContent = `Selected note ${Number(id) + 1}`;
+                },
+              }),
+        );
+      };
+      render();
+      container.append(
+        card({
+          title: 'Notes',
+          children: [
+            textField({
+              label: 'Note text',
+              onInput: (value) => {
+                draft = value;
+              },
+            }),
+            button({
+              label: 'Add',
+              variant: 'primary',
+              onClick: () => {
+                if (draft.trim() === '') return;
+                notes.push(draft.trim());
+                status.textContent = `Notes: ${notes.length}`;
+                render();
+              },
+            }),
+            body,
+          ],
+        }),
+        status,
+      );
+    },
+  }),
+} satisfies ExtensionPanels;
+```
+
+- `list`, `button`, `textField`, `select`, `toggle`, `card` and `emptyState`
+  return DOM elements you append yourself. Each has a role, a visible name and
+  keyboard control (a `list` is one tab stop, arrows move, Enter or Space
+  select).
+- Colours and spacing come from the CSS variables of the frame theme, so the
+  light and the dark theme work with no code of yours. Text is always set as
+  `textContent`; the kit never parses markup.
+- Elements keep no state of their own. To change a list, build a new one and
+  call `replaceWith` / `replaceChildren`.
+- The whole kit is under 10 KiB gzipped, and it adds no permission: the panel
+  still runs in the isolated frame with no network.
+
+## The test
+
+File `test/index.test.ts` (ui-kit):
+
+```ts
+// @vitest-environment happy-dom
+import { loadPanel } from '@dolphy-app/extension-sdk/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+import { panels } from '../src/index.ts';
+
+const disposables: { dispose(): unknown }[] = [];
+afterEach(async () => {
+  await Promise.all(disposables.splice(0).map((item) => item.dispose()));
+});
+
+describe('acme.hello: panel', () => {
+  it('starts with an empty state and lists an added note', async () => {
+    const panel = await loadPanel(panels, 'acme.hello.view');
+    disposables.push(panel);
+    expect(panel.container.textContent).toContain('No notes yet');
+
+    const input = panel.container.querySelector('input') as HTMLInputElement;
+    input.value = 'Buy milk';
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    const add = [...panel.container.querySelectorAll('button')].find(
+      (element) => element.textContent === 'Add',
+    ) as HTMLButtonElement;
+    add.click();
+
+    const options = panel.container.querySelectorAll('[role="option"]');
+    expect(options).toHaveLength(1);
+    expect(options[0]?.textContent).toContain('Buy milk');
+    expect(panel.container.querySelector('[role="status"]')?.textContent).toBe(
+      'Notes: 1',
+    );
+  });
+
+  it('ignores an empty note', async () => {
+    const panel = await loadPanel(panels, 'acme.hello.view');
+    disposables.push(panel);
+    const add = [...panel.container.querySelectorAll('button')].find(
+      (element) => element.textContent === 'Add',
+    ) as HTMLButtonElement;
+    add.click();
+    expect(panel.container.textContent).toContain('No notes yet');
+  });
+});
+```
+
+`loadPanel` mounts the panel in happy-dom the way the frame does. The kit's
+own tests check its roles and keys; test what your panel does with them.
+
+## Try and ship
+
+Run `pnpm dev`, start the app with `DOLPHY_DEV_EXTENSIONS` and open the panel
+from the sidebar. Switch the theme in Settings → Appearance: the panel follows.

package/docs/recipe-when-dependencies.md

@@ -0,0 +1,158 @@
+# Recipe: visibility conditions and dependencies
+
+Show a command, a panel or a widget only where it makes sense (`when`), and
+require another extension (`dependencies`). Both are manifest data, so this
+recipe is a small project whose test reads the manifest. 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` (when-dependencies):
+
+```json
+{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
+  "id": "acme.hello",
+  "version": "0.1.0",
+  "apiVersion": 1,
+  "name": "Hello report",
+  "description": "A report command that appears only on the Courses screen.",
+  "author": "your-github-login",
+  "tags": ["productivity"],
+  "dependencies": [
+    { "id": "acme.cards", "range": ">=1.0.0 <2.0.0" },
+    { "id": "dolphy.choice" }
+  ],
+  "contributes": {
+    "commands": [
+      {
+        "id": "acme.hello.report",
+        "title": "Course report",
+        "when": "route == 'courses' && course.active"
+      }
+    ],
+    "panels": [
+      {
+        "id": "acme.hello.board",
+        "title": "Course board",
+        "when": "course.active && !session.active"
+      }
+    ]
+  }
+}
+```
+
+- `when` is a boolean expression over five keys of the app window: `route`
+  (the name of the current screen), `course.active` (one course is in focus),
+  `session.active` (a study session is open), `locale` (`ru` or `en`) and
+  `theme.dark`. Operators: `==`, `!=`, `in ('a', 'b')`, `&&`, `||`, `!` and
+  parentheses; strings are in single quotes. At most 200 characters. An unknown
+  key or value, a wrong type or a syntax error is a manifest error with the
+  position, so `pnpm validate` catches a typo before the app does.
+- While the condition is false a command is not in the palette and its keys do
+  nothing, a panel's menu item is hidden, and a widget is not drawn. The value
+  follows the route, the course, the session, the language and the theme
+  without a reload. Your own code still reaches the command (`ctx.call`) and
+  the panel (`openPanel`): `when` hides, it does not forbid.
+- `dependencies` lists up to 16 extensions that must be present, enabled,
+  loaded and in the version `range` (comparators separated by a space, such as
+  `>=1.0.0 <2.0.0`; no `^` or `~`). Otherwise the extension is shown as
+  "dependencies not met" in Settings → Extensions, with the missing, disabled
+  or mismatched one named, and contributes nothing. Disabling or enabling a
+  dependency updates the dependents at once.
+- Nothing installs a dependency for the user, and extensions cannot call each
+  other: a dependency only says "this must be there". A repeat and a dependency
+  on yourself are manifest errors; extensions that depend on each other in a
+  circle are not loaded.
+
+## The code
+
+File `src/index.ts` (when-dependencies):
+
+```ts
+import { defineExtension, defineExtensionPanel } from '@dolphy-app/extension-sdk';
+import type { ExtensionPanels } from '@dolphy-app/extension-sdk';
+
+export const host = defineExtension({
+  commands: { 'acme.hello.report': () => ({ courses: 1 }) },
+});
+
+export const panels = {
+  'acme.hello.board': defineExtensionPanel({
+    mount(container) {
+      container.textContent = 'Board';
+    },
+  }),
+} satisfies ExtensionPanels;
+```
+
+The conditions are in the manifest, so the code is ordinary: it does not check
+where it is shown. The command and the panel are only reachable where the
+condition is true.
+
+## The test
+
+File `test/when.test.ts` (when-dependencies):
+
+```ts
+import { evaluateWhen, parseWhen } from '@dolphy-app/extension-sdk';
+import type { WhenContext } from '@dolphy-app/extension-sdk';
+import { describe, expect, it } from 'vitest';
+import manifest from '../extension.json';
+
+const context = (overrides: Partial<WhenContext> = {}): WhenContext => ({
+  route: 'courses',
+  'course.active': true,
+  'session.active': false,
+  locale: 'en',
+  'theme.dark': false,
+  ...overrides,
+});
+
+const [command] = manifest.contributes.commands;
+const [panel] = manifest.contributes.panels;
+
+describe('acme.hello: when', () => {
+  it('shows the report on the Courses screen with a course in focus', () => {
+    const when = parseWhen(command.when);
+    expect(evaluateWhen(when, context())).toBe(true);
+    expect(evaluateWhen(when, context({ route: 'daily-plan' }))).toBe(
+      false,
+    );
+    expect(
+      evaluateWhen(when, context({ 'course.active': false })),
+    ).toBe(false);
+  });
+
+  it('hides the board during a study session', () => {
+    const when = parseWhen(panel.when);
+    expect(evaluateWhen(when, context())).toBe(true);
+    expect(
+      evaluateWhen(when, context({ 'session.active': true })),
+    ).toBe(false);
+  });
+
+  it('reports a typo in a key with its position', () => {
+    expect(() => parseWhen("rout == 'courses'")).toThrow();
+  });
+});
+
+describe('acme.hello: dependencies', () => {
+  it('names each required extension once, and not itself', () => {
+    const ids = manifest.dependencies.map(({ id }) => id);
+    expect(new Set(ids).size).toBe(ids.length);
+    expect(ids).not.toContain(manifest.id);
+  });
+});
+```
+
+`parseWhen` and `evaluateWhen` are the functions the app and `dolphy-ext
+validate` use. `evaluateWhen` is pure: pass an object with the five keys.
+
+## Try and ship
+
+Run `pnpm validate`: it fails on a bad `when` or a bad `dependencies` entry.
+In the app the extension's row in Settings → Extensions shows "dependencies not
+met" until `acme.cards` is installed and enabled.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dolphy-app/extension-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "SDK for extension authors: defineExtension, defineAnswerView, test helpers",
   "type": "module",
   "sideEffects": false,
@@ -20,10 +20,11 @@
   },
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "dependencies": {
-    "@dolphy-app/extension-api": "0.3.0",
+    "@dolphy-app/extension-api": "0.4.0",
     "ajv": "^8"
   },
   "engines": {