@dolphy-app/extension-sdk 0.3.0 → 0.5.0

package/docs/recipe-when-dependencies.md

@@ -0,0 +1,264 @@
+# Recipe: visibility conditions, a widget and dependencies
+
+Show a command or a panel only where it makes sense (`when`), draw a component
+into a screen of the app (an injection), and require another extension
+(`dependencies`). This recipe has no template of its own: start from `blank`
+and replace the 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" }
+  ]
+}
+```
+
+`dependencies` is the only part of this recipe that lives in the manifest: 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
+export { client } from './client.ts';
+export { server } from './server.ts';
+```
+
+File `src/server.ts` (when-dependencies):
+
+```ts
+import { defineServer } from '@dolphy-app/extension-sdk';
+
+export const server = defineServer((s) => {
+  s.registerCommand({
+    id: 'acme.hello.report',
+    title: { en: 'Course report', ru: 'Отчёт по курсу' },
+    when: "route == 'courses' && course.active",
+    run: () => ({ courses: 1 }),
+  });
+});
+```
+
+File `src/client.ts` (when-dependencies):
+
+```ts
+import { anchorSelector, defineClient } from '@dolphy-app/extension-sdk';
+import { Board } from './board.ts';
+import { PlanNote } from './plan-note.ts';
+
+export const client = defineClient((c) => {
+  c.addPanel({
+    id: 'acme.hello.board',
+    title: { en: 'Course board', ru: 'Доска курса' },
+    when: 'course.active && !session.active',
+    component: Board,
+  });
+
+  // drawn inside the "Daily plan" screen, at the anchor the app keeps stable
+  c.addInjection({
+    id: 'acme.hello.plan-note',
+    target: anchorSelector('dailyPlan'),
+    component: PlanNote,
+  });
+});
+```
+
+File `src/board.ts` (when-dependencies):
+
+```ts
+import { defineComponent, h } from 'vue';
+
+export const Board = defineComponent({
+  setup: () => () => h('p', 'Board'),
+});
+```
+
+File `src/plan-note.ts` (when-dependencies):
+
+```ts
+import { useInjection } from '@dolphy-app/extension-sdk/client';
+import { defineComponent, h } from 'vue';
+
+// `useInjection()` tells the component where the app drew it
+export const PlanNote = defineComponent({
+  setup() {
+    const injection = useInjection();
+    return () => h('p', `Drawn at the daily plan: ${injection.position}`);
+  },
+});
+```
+
+- `when` is a boolean expression over five keys of the app window: `route`
+  (the name of the current screen, one of `WHEN_ROUTES`), `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. It goes on a command (`server.registerCommand`, also on one of its
+  `keybindings`), a client command (`client.addCommand`) or a panel
+  (`client.addPanel`). An unknown key or value, a wrong type or a syntax error
+  fails the registration with the position in the message.
+- While the condition is false a command is not in the palette and its keys do
+  nothing, and a panel's menu item is hidden. The value follows the route, the
+  course, the session, the language and the theme without a reload. Your own code
+  still reaches the command (`panel.call`) and the panel (`openPanel`): `when`
+  hides, it does not forbid.
+- `client.addInjection({ id, target, position?, component })` draws the
+  component at every element that matches the CSS selector `target`: `before` or
+  `after` it, or inside it as its first (`prepend`) or last (`append`, the
+  default) child. The window watches its DOM: the component is mounted when a
+  target appears and removed when it goes away or when the extension is
+  unloaded. An injection has no `when`: it exists where the target does.
+- `anchorSelector('dailyPlan')` is `[data-ext-anchor="dailyPlan"]`, the place
+  the app marks in the "Daily plan" screen and keeps stable. Any other selector
+  depends on the markup of the app, which can change between versions, so the
+  injection may silently stop finding its target after an update; prefer an
+  anchor.
+- The injected component runs in the app's own tree: `inject`, Vuetify, the
+  theme and the language work. A failure shows an error card in its place and
+  does not touch the rest of the window.
+
+## The test
+
+File `test/index.test.ts` (when-dependencies):
+
+```ts
+// @vitest-environment happy-dom
+import {
+  INJECTION_HANDLE_KEY,
+  anchorSelector,
+  evaluateWhen,
+  parseWhen,
+} from '@dolphy-app/extension-sdk';
+import type { WhenContext } from '@dolphy-app/extension-sdk';
+import {
+  createTestClient,
+  createTestServer,
+} from '@dolphy-app/extension-sdk/testing';
+import { describe, expect, it } from 'vitest';
+import { createApp, h } from 'vue';
+import manifest from '../extension.json';
+import { client, server } from '../src/index.ts';
+import { PlanNote } from '../src/plan-note.ts';
+
+const context = (overrides: Partial<WhenContext> = {}): WhenContext => ({
+  route: 'courses',
+  'course.active': true,
+  'session.active': false,
+  locale: 'en',
+  'theme.dark': false,
+  ...overrides,
+});
+
+const parsed = (when: string | null | undefined) => {
+  if (when === null || when === undefined) throw new Error('no condition');
+  return parseWhen(when);
+};
+
+describe('acme.hello: when', () => {
+  it('shows the report on the Courses screen with a course in focus', async () => {
+    const running = await createTestServer(server, {
+      extensionId: 'acme.hello',
+    });
+    const report = running.registration.commands.find(
+      ({ id }) => id === 'acme.hello.report',
+    );
+    const when = parsed(report?.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);
+    await running.dispose();
+  });
+
+  it('hides the board during a study session', async () => {
+    const running = await createTestClient(client, {
+      extensionId: 'acme.hello',
+    });
+    const board = running.panels.find(({ id }) => id === 'acme.hello.board');
+    const when = parsed(board?.when);
+    expect(evaluateWhen(when, context())).toBe(true);
+    expect(evaluateWhen(when, context({ 'session.active': true }))).toBe(false);
+    await running.dispose();
+  });
+
+  it('reports a typo in a key with its position', () => {
+    expect(() => parseWhen("rout == 'courses'")).toThrow();
+  });
+});
+
+describe('acme.hello: injection', () => {
+  it('is drawn at the anchor of the daily plan', async () => {
+    const running = await createTestClient(client, {
+      extensionId: 'acme.hello',
+    });
+    expect(running.injections).toEqual([
+      {
+        id: 'acme.hello.plan-note',
+        target: anchorSelector('dailyPlan'),
+        position: 'append',
+        component: PlanNote,
+      },
+    ]);
+    await running.dispose();
+  });
+
+  it('the component reads where the app drew it', () => {
+    const host = document.createElement('div');
+    const app = createApp({ render: () => h(PlanNote) });
+    app.provide(INJECTION_HANDLE_KEY, {
+      target: document.createElement('div'),
+      position: 'append',
+    });
+    app.mount(host);
+    expect(host.textContent).toBe('Drawn at the daily plan: append');
+    app.unmount();
+  });
+});
+
+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);
+  });
+});
+```
+
+`createTestServer` and `createTestClient` hand the test what the code
+registered: `running.registration.commands` for the server (with `when` as
+registered) and `running.panels` and `running.injections` for the client. The
+test feeds that text to `parseWhen` and `evaluateWhen`, the functions the app
+uses; `evaluateWhen` is pure, so pass an object with the five keys. The
+dependencies are manifest data, so the test reads `extension.json`.
+
+## Try and ship
+
+Run `pnpm build` and `pnpm validate`, which fails on a bad `dependencies`
+entry. The test parses every `when`, so `pnpm test` catches a typo before the
+app does (the app fails the registration with the position). In the app the
+extension's row in Settings → Extensions shows "dependencies not met" until
+`acme.cards` is installed and enabled. Open the Daily plan screen to see the
+injected note.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dolphy-app/extension-sdk",
-  "version": "0.3.0",
-  "description": "SDK for extension authors: defineExtension, defineAnswerView, test helpers",
+  "version": "0.5.0",
+  "description": "SDK for extension authors: defineServer, defineClient, defineRpc, usePanel, useInjection, useApp, useEngine, useRpc, defineMountable, callRpc, reactComponent, test harness",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -9,22 +9,45 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./runtime": {
-      "types": "./dist/runtime.d.ts",
-      "default": "./dist/runtime.js"
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./rpc": {
+      "types": "./dist/rpc.d.ts",
+      "default": "./dist/rpc.js"
     },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "default": "./dist/testing.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
     }
   },
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "dependencies": {
-    "@dolphy-app/extension-api": "0.3.0",
-    "ajv": "^8"
+    "@dolphy-app/extension-api": "0.5.0",
+    "ajv": "^8",
+    "zod": "4.6.5"
+  },
+  "peerDependencies": {
+    "vue": "^3.5",
+    "react": "^19",
+    "react-dom": "^19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=22.12"

package/dist/answer-element-BOQcuxYh.js

@@ -1,114 +0,0 @@
-import { ANSWER_EVENT, ELEMENT_NAME_PATTERN } from "@dolphy-app/extension-api";
-
-//#region packages/extension-sdk/src/answer-element.ts
-const logFailure = (tag, message, error) => {
-	console.error({
-		error,
-		tag
-	}, message);
-};
-const createAnswerElementClass = (tag, answerView) => class AnswerElement extends HTMLElement {
-	#root = this.attachShadow({ mode: "open" });
-	#props = {
-		view: void 0,
-		value: void 0,
-		disabled: false,
-		verdict: null
-	};
-	#instance = null;
-	#isFlushScheduled = false;
-	get view() {
-		return this.#props.view;
-	}
-	set view(view) {
-		this.#change({ view });
-	}
-	get value() {
-		return this.#props.value;
-	}
-	set value(value) {
-		this.#change({ value });
-	}
-	get disabled() {
-		return this.#props.disabled;
-	}
-	set disabled(disabled) {
-		this.#change({ disabled });
-	}
-	get verdict() {
-		return this.#props.verdict;
-	}
-	set verdict(verdict) {
-		this.#change({ verdict });
-	}
-	connectedCallback() {
-		if (this.#instance !== null) return;
-		const readLabel = () => this.getAttribute("aria-label");
-		const api = {
-			root: this.#root,
-			get label() {
-				return readLabel();
-			},
-			setAnswer: (value, complete) => {
-				const detail = {
-					value,
-					complete
-				};
-				this.#emit(ANSWER_EVENT.change, detail);
-			},
-			submit: () => this.#emit(ANSWER_EVENT.submit, void 0)
-		};
-		try {
-			this.#instance = answerView.mount(api, Object.freeze({ ...this.#props }));
-		} catch (error) {
-			logFailure(tag, "answer element failed to mount", error);
-		}
-	}
-	disconnectedCallback() {
-		const instance = this.#instance;
-		this.#instance = null;
-		if (instance === null) return;
-		try {
-			instance.destroy?.();
-		} catch (error) {
-			logFailure(tag, "answer element failed to destroy", error);
-		}
-		this.#root.replaceChildren();
-	}
-	#change(patch) {
-		this.#props = {
-			...this.#props,
-			...patch
-		};
-		if (this.#instance === null || this.#isFlushScheduled) return;
-		this.#isFlushScheduled = true;
-		queueMicrotask(() => this.#flush());
-	}
-	#flush() {
-		this.#isFlushScheduled = false;
-		const instance = this.#instance;
-		if (instance === null) return;
-		try {
-			instance.update(Object.freeze({ ...this.#props }));
-		} catch (error) {
-			logFailure(tag, "answer element failed to update", error);
-		}
-	}
-	#emit(name, detail) {
-		this.dispatchEvent(new CustomEvent(name, {
-			detail,
-			bubbles: true,
-			composed: true
-		}));
-	}
-};
-/** Defines the kind's custom element; calling again with the same tag changes nothing. */
-const registerAnswerView = (tag, view) => {
-	if (!ELEMENT_NAME_PATTERN.test(tag)) throw new TypeError(`invalid custom element name '${tag}'`);
-	if (typeof view?.mount !== "function") throw new TypeError(`answer view for '${tag}' has no mount()`);
-	if (customElements.get(tag) !== void 0) return;
-	customElements.define(tag, createAnswerElementClass(tag, view));
-};
-
-//#endregion
-export { registerAnswerView as n, createAnswerElementClass as t };

package/dist/answer-view-D6wnyThb.d.ts

@@ -1,28 +0,0 @@
-import { AnswerElementProps } from "@dolphy-app/extension-api";
-//#region packages/extension-sdk/src/answer-view.d.ts
-interface AnswerViewApi {
-  readonly root: ShadowRoot;
-  /** `aria-label` of the host element set by the app; `null` if none. */
-  readonly label: string | null;
-  /** Reports the current answer to the app: the `dolphy-answer-change` event. */
-  setAnswer(value: unknown, complete: boolean): void;
-  /** Asks the app to submit the answer: the `dolphy-answer-submit` event. */
-  submit(): void;
-}
-interface AnswerViewInstance {
-  /** Called when `view`/`value`/`disabled`/`verdict` change. */
-  update(props: AnswerElementProps): void;
-  destroy?(): void;
-}
-type MountAnswerView = (api: AnswerViewApi, props: AnswerElementProps) => AnswerViewInstance;
-/** Description of an answer input view: side-effect-free data; the build registers the element. */
-interface AnswerView {
-  readonly mount: MountAnswerView;
-}
-/**
- * Entry `views[<exercise kind id>]` in `src/index.ts`. Registers nothing:
- * the custom element with the manifest tag is defined by the build's browser file.
- */
-declare const defineAnswerView: (mount: MountAnswerView) => AnswerView;
-//#endregion
-export { defineAnswerView as a, MountAnswerView as i, AnswerViewApi as n, AnswerViewInstance as r, AnswerView as t };

package/dist/runtime.d.ts

@@ -1,14 +0,0 @@
-import { t as AnswerView } from "./answer-view-D6wnyThb.js";
-import { MarkdownRendererModule, PanelModule } from "@dolphy-app/extension-api";
-//#region packages/extension-sdk/src/answer-element.d.ts
-/** Defines the kind's custom element; calling again with the same tag changes nothing. */
-export declare const registerAnswerView: (tag: string, view: AnswerView) => void;
-//#endregion
-//#region packages/extension-sdk/src/runtime.d.ts
-type PanelEntry = PanelModule<HTMLElement>;
-type MarkdownEntry = MarkdownRendererModule<HTMLElement>;
-/** Panel module that selects the `panels` entry by `ctx.panelId` (for a file shared by several panels). */
-export declare const dispatchPanels: (panels: Readonly<Record<string, PanelEntry>>) => PanelEntry;
-/** Renderer module that selects the `markdown` entry by block language. */
-export declare const dispatchMarkdown: (renderers: Readonly<Record<string, MarkdownEntry>>) => MarkdownEntry;
-//#endregion

package/dist/runtime.js

@@ -1,18 +0,0 @@
-import { n as registerAnswerView } from "./answer-element-BOQcuxYh.js";
-
-//#region packages/extension-sdk/src/runtime.ts
-/** Panel module that selects the `panels` entry by `ctx.panelId` (for a file shared by several panels). */
-const dispatchPanels = (panels) => ({ mount(container, context) {
-	const panel = panels[context.panelId];
-	if (panel === void 0) throw new Error(`panel '${context.panelId}' is not exported`);
-	return panel.mount(container, context);
-} });
-/** Renderer module that selects the `markdown` entry by block language. */
-const dispatchMarkdown = (renderers) => ({ render(source, container, context) {
-	const renderer = renderers[context.language];
-	if (renderer === void 0) throw new Error(`markdown renderer '${context.language}' is not exported`);
-	return renderer.render(source, container, context);
-} });
-
-//#endregion
-export { dispatchMarkdown, dispatchPanels, registerAnswerView };