@dolphy-app/extension-sdk 0.4.0 → 0.6.0

package/README.md

@@ -1,19 +1,30 @@
 # @dolphy-app/extension-sdk
 
-SDK for extension authors: defineExtension, defineAnswerView, test helpers
-
-The package version equals the version of the Dolphy app release it was published from (0.4.0).
-
-`@dolphy-app/extension-sdk` — extension code (`defineExtension`,
-`defineExerciseType`), answer views (`defineAnswerView`), panels,
-markdown renderers and test helpers (`@dolphy-app/extension-sdk/testing`).
-The package has no side effects: an extension `src/index.ts` can be
-imported in plain Node. Ids declared in `extension.json` become types
-through `.dolphy/ids.d.ts`, which `dolphy-ext types` generates.
+SDK for extension authors: defineServer, defineClient, defineRpc, usePanel, useInjection, useApp, useEngine, useRpc, defineMountable, callRpc, reactComponent, test harness
+
+The package version equals the version of the Dolphy app release it was published from (0.6.0).
+
+`@dolphy-app/extension-sdk` — extension code: `defineServer` and
+`defineClient` describe the `server` and `client` exports of an extension
+`src/index.ts`, `defineRpc` declares a call from a component to the server
+part. Components of the client part use `useApp`, `useEngine`, `useRpc`,
+`usePanel` and `useInjection` (`@dolphy-app/extension-sdk/client`; `vue` is a
+peer dependency). A component is a Vue component (single-file `.vue`
+components included) or a `Mountable` that `defineMountable` builds and that
+draws with any framework; `reactComponent` and the React hooks
+(`@dolphy-app/extension-sdk/react`) draw a React component, `react` and
+`react-dom` being optional peer dependencies. `createTestServer`,
+`createTestClient` and `mountForTest` (`@dolphy-app/extension-sdk/testing`)
+run an extension against in-memory implementations of the app. The package
+has no side effects: an extension `src/index.ts` can be imported in plain
+Node.
 
 ```ts
-import { defineExtension } from '@dolphy-app/extension-sdk';
-import { loadExerciseType } from '@dolphy-app/extension-sdk/testing';
+import { defineClient, defineServer } from '@dolphy-app/extension-sdk';
+import { defineRpc } from '@dolphy-app/extension-sdk/rpc';
+import { useApp, useRpc } from '@dolphy-app/extension-sdk/client';
+import { reactComponent } from '@dolphy-app/extension-sdk/react';
+import { createTestServer } from '@dolphy-app/extension-sdk/testing';
 ```
 
 The package ships a guide in `docs/` (`node_modules/@dolphy-app/extension-sdk/docs/`
@@ -22,11 +33,14 @@ after the install): a
 [an exercise type](https://github.com/dolphy-app/dolphy/blob/main/packages/extension-sdk/docs/recipe-exercise-type.md),
 [a theme](https://github.com/dolphy-app/dolphy/blob/main/packages/extension-sdk/docs/recipe-theme.md),
 [a command and a panel](https://github.com/dolphy-app/dolphy/blob/main/packages/extension-sdk/docs/recipe-command-panel.md),
+[a panel in React](https://github.com/dolphy-app/dolphy/blob/main/packages/extension-sdk/docs/recipe-react.md),
+[a component of any framework](https://github.com/dolphy-app/dolphy/blob/main/packages/extension-sdk/docs/recipe-mountable.md),
 [events and storage](https://github.com/dolphy-app/dolphy/blob/main/packages/extension-sdk/docs/recipe-event-storage.md),
+[hooks before a session and a batch](https://github.com/dolphy-app/dolphy/blob/main/packages/extension-sdk/docs/recipe-hooks.md),
+[calls between the parts, the engine and the window](https://github.com/dolphy-app/dolphy/blob/main/packages/extension-sdk/docs/recipe-rpc-and-app.md),
 [settings](https://github.com/dolphy-app/dolphy/blob/main/packages/extension-sdk/docs/recipe-settings.md),
 [an importer and an exporter](https://github.com/dolphy-app/dolphy/blob/main/packages/extension-sdk/docs/recipe-import-export.md),
-[visibility conditions and dependencies](https://github.com/dolphy-app/dolphy/blob/main/packages/extension-sdk/docs/recipe-when-dependencies.md) and
-[a panel on the UI kit](https://github.com/dolphy-app/dolphy/blob/main/packages/extension-sdk/docs/recipe-ui-kit.md), a path
+[visibility conditions and dependencies](https://github.com/dolphy-app/dolphy/blob/main/packages/extension-sdk/docs/recipe-when-dependencies.md), a path
 [without a build](https://github.com/dolphy-app/dolphy/blob/main/packages/extension-sdk/docs/no-build.md) and notes on
 [debugging](https://github.com/dolphy-app/dolphy/blob/main/packages/extension-sdk/docs/debugging.md).
 

package/dist/client.d.ts

@@ -0,0 +1,40 @@
+import { t as ExtensionEngine } from "./index-I_CXC6Lj.js";
+import { t as AppApi$1 } from "./define-entry-lsuxzKdD.js";
+import { InjectionHandle, PanelHandle, RpcContract } from "@dolphy-app/extension-api";
+//#region packages/extension-sdk/src/client.d.ts
+/**
+ * The handle of the panel the component is drawn for: its id, the reactive
+ * `props` it was opened with, the reactive `context` and `call` for the
+ * commands of this extension. Only inside a panel component of the app.
+ */
+export declare const usePanel: <Commands extends string = string>() => PanelHandle<Commands>;
+/**
+ * The handle of the injected component: the `target` element it is drawn at
+ * and the `position` relative to it. Only inside a component that
+ * `client.addInjection` registered.
+ */
+export declare const useInjection: () => InjectionHandle;
+/**
+ * What the window lets an extension do: open a course, a lesson, an exercise,
+ * a panel or settings, show a toast, read the theme and the language, run a
+ * palette command, mount a component into an element. `theme` and `locale`
+ * are reactive. Only inside a component that the app draws.
+ */
+export declare const useApp: () => AppApi$1;
+/**
+ * The engine client of the window: every method of the engine contract,
+ * writing ones included, and `subscribe` for the engine events. Only inside a
+ * component that the app draws.
+ */
+export declare const useEngine: () => ExtensionEngine;
+/**
+ * Binds the contract to the server part of this extension: the returned
+ * function validates the input with `contract.input`, calls the handler of
+ * `server.handle` and validates the answer with `contract.output`. A schema
+ * violation, an error of the handler and an unavailable server reject the
+ * promise with an `Error` that carries the message. Call it in `setup`: it
+ * reads the extension id and the engine from the component's context. Only
+ * inside a component of an extension that the app draws.
+ */
+export declare const useRpc: <Input, Output>(contract: RpcContract<Input, Output>) => ((input: Input) => Promise<Output>);
+//#endregion

package/dist/client.js

@@ -0,0 +1,67 @@
+import { callRpc } from "./rpc.js";
+import { APP_KEY, ENGINE_KEY, EXTENSION_ID_KEY, INJECTION_HANDLE_KEY, PANEL_HANDLE_KEY } from "@dolphy-app/extension-api";
+import { inject } from "vue";
+
+//#region packages/extension-sdk/src/client.ts
+/**
+* The handle of the panel the component is drawn for: its id, the reactive
+* `props` it was opened with, the reactive `context` and `call` for the
+* commands of this extension. Only inside a panel component of the app.
+*/
+const usePanel = () => {
+	const handle = inject(PANEL_HANDLE_KEY, null);
+	if (handle === null) throw new Error("usePanel() works inside a panel component that the app draws, there is no panel here");
+	return handle;
+};
+/**
+* The handle of the injected component: the `target` element it is drawn at
+* and the `position` relative to it. Only inside a component that
+* `client.addInjection` registered.
+*/
+const useInjection = () => {
+	const handle = inject(INJECTION_HANDLE_KEY, null);
+	if (handle === null) throw new Error("useInjection() works inside an injected component that the app draws, there is no injection here");
+	return handle;
+};
+/**
+* What the window lets an extension do: open a course, a lesson, an exercise,
+* a panel or settings, show a toast, read the theme and the language, run a
+* palette command, mount a component into an element. `theme` and `locale`
+* are reactive. Only inside a component that the app draws.
+*/
+const useApp = () => {
+	const app = inject(APP_KEY, null);
+	if (app === null) throw new Error("useApp() works inside a component that the app draws, there is no app here");
+	return app;
+};
+/**
+* The engine client of the window: every method of the engine contract,
+* writing ones included, and `subscribe` for the engine events. Only inside a
+* component that the app draws.
+*/
+const useEngine = () => {
+	const engine = inject(ENGINE_KEY, null);
+	if (engine === null) throw new Error("useEngine() works inside a component that the app draws, there is no engine here");
+	return engine;
+};
+/**
+* Binds the contract to the server part of this extension: the returned
+* function validates the input with `contract.input`, calls the handler of
+* `server.handle` and validates the answer with `contract.output`. A schema
+* violation, an error of the handler and an unavailable server reject the
+* promise with an `Error` that carries the message. Call it in `setup`: it
+* reads the extension id and the engine from the component's context. Only
+* inside a component of an extension that the app draws.
+*/
+const useRpc = (contract) => {
+	const extensionId = inject(EXTENSION_ID_KEY, null);
+	if (extensionId === null) throw new Error("useRpc() works inside a component of an extension that the app draws, there is no extension here");
+	const engine = useEngine();
+	return (input) => callRpc({
+		engine,
+		extensionId
+	}, contract, input);
+};
+
+//#endregion
+export { useApp, useEngine, useInjection, usePanel, useRpc };

package/dist/define-entry-BTz2F3qv.js

@@ -0,0 +1,22 @@
+import { MOUNTABLE } from "@dolphy-app/extension-api";
+
+//#region packages/extension-sdk/src/define-entry.ts
+/**
+* `export const panel = defineMountable<PanelProps, PanelHandle>((el, ctx) => { … return () => … })`:
+* a component of any framework. `mount` draws into `el` and returns the
+* cleanup that the app calls when it removes the element. Returns an object
+* that carries the brand `isMountable` recognises.
+*/
+const defineMountable = /* @__NO_SIDE_EFFECTS__ */ (mount) => ({
+	[MOUNTABLE]: true,
+	mount
+});
+/** `export const server = defineServer((server) => { … })`: registers the server contributions. Returns `entry` as is; it only checks the types. */
+const defineServer = /* @__NO_SIDE_EFFECTS__ */ (entry) => entry;
+/** `export const client = defineClient((client) => { … })`: registers the client contributions. Returns `entry` as is; it only checks the types. */
+const defineClient = /* @__NO_SIDE_EFFECTS__ */ (entry) => entry;
+/** An exercise type registration with `Spec`, `Answer` and `View` inferred from the handlers; pass it to `server.registerExerciseType`. */
+const defineExerciseType = /* @__NO_SIDE_EFFECTS__ */ (registration) => registration;
+
+//#endregion
+export { defineServer as i, defineExerciseType as n, defineMountable as r, defineClient as t };

package/dist/define-entry-lsuxzKdD.d.ts

@@ -0,0 +1,77 @@
+import { t as ExtensionEngine } from "./index-I_CXC6Lj.js";
+import { AnswerViewProps, AppApi, ClientContext, Disposable, EntryResult, ExerciseTypeRegistration, InjectionHandle, InjectionProps, InjectionRegistration, MOUNTABLE, MarkdownBlockProps, MountContext, PanelHandle, PanelProps, PanelRegistration, ServerContext, ServerEntry, SettingValues, Unmount } from "@dolphy-app/extension-api";
+import { Component } from "vue";
+//#region packages/extension-sdk/src/define-entry.d.ts
+/**
+ * What the host gives the server part of an extension: `ServerContext` of the
+ * API with `engine` typed as `ExtensionEngine`.
+ */
+type ServerContext$1<S extends SettingValues = SettingValues> = ServerContext<S, ExtensionEngine>;
+/** `export const server` of `src/index.ts`: registers the server contributions; the result, if any, runs when the extension is unloaded. */
+type ServerEntry$1 = ServerEntry<ExtensionEngine>;
+/**
+ * The window capabilities of `useApp()` and `ClientContext.app`: `AppApi` of
+ * the API with the component of `mountAt` typed as a Vue component.
+ */
+interface AppApi$1 extends Omit<AppApi, 'mountAt'> {
+  /** Mounts a Vue component into an element of the window, see `AppApi.mountAt` of the API; the props are passed to the component as is. */
+  mountAt(target: Element | string, component: Component, props?: Readonly<Record<string, unknown>>): Disposable;
+}
+/**
+ * What a `Mountable` gets: `MountContext` of the API with `engine` typed as
+ * `ExtensionEngine` and `app` as `AppApi`. `Handle` is `PanelHandle` in a
+ * panel, `InjectionHandle` in an injection, `undefined` elsewhere.
+ */
+interface MountContext$1<Props = unknown, Handle = undefined> extends Omit<MountContext<Props, ExtensionEngine, Handle>, 'app'> {
+  readonly app: AppApi$1;
+}
+/**
+ * A component of any framework: `mount` draws into `el` and returns the
+ * cleanup (see `Mountable` of the API). Build it with `defineMountable`.
+ */
+interface Mountable<Props = unknown, Handle = undefined> {
+  readonly [MOUNTABLE]: true;
+  mount(el: HTMLElement, ctx: MountContext$1<Props, Handle>): Unmount | Promise<Unmount>;
+}
+/** A panel: an app screen drawn by a Vue component or a `Mountable` of the extension (`client.addPanel`). */
+interface PanelRegistration$1 extends Omit<PanelRegistration, 'component'> {
+  /** Inside a Vue component `usePanel()` reaches the props and the commands, in a `Mountable` `ctx.handle` does. */
+  component: Component | Mountable<PanelProps, PanelHandle>;
+}
+/** A component drawn in the window at the elements that match `target` (`client.addInjection`). */
+interface InjectionRegistration$1 extends Omit<InjectionRegistration, 'component'> {
+  /** Inside a Vue component `useInjection()` reaches the target element and the position, in a `Mountable` `ctx.handle` does. */
+  component: Component | Mountable<InjectionProps, InjectionHandle>;
+}
+/**
+ * What the window gives the client part of an extension: `ClientContext` of
+ * the API with the components typed as Vue components or `Mountable`s, `app`
+ * typed as `AppApi` and `engine` as `ExtensionEngine`.
+ */
+interface ClientContext$1 extends Omit<ClientContext<ExtensionEngine>, 'app' | 'addPanel' | 'addInjection' | 'addAnswerView' | 'addMarkdownRenderer'> {
+  /** The same object as `useApp()` in a component. */
+  readonly app: AppApi$1;
+  addPanel(reg: PanelRegistration$1): Disposable;
+  addInjection(reg: InjectionRegistration$1): Disposable;
+  /** The component takes the `AnswerViewProps` props and emits `change` (`AnswerChange`) and `submit`. */
+  addAnswerView(exerciseTypeId: string, component: Component | Mountable<AnswerViewProps>): Disposable;
+  /** The component takes the `MarkdownBlockProps` props. */
+  addMarkdownRenderer(language: string, component: Component | Mountable<MarkdownBlockProps>): Disposable;
+}
+/**
+ * `export const panel = defineMountable<PanelProps, PanelHandle>((el, ctx) => { … return () => … })`:
+ * a component of any framework. `mount` draws into `el` and returns the
+ * cleanup that the app calls when it removes the element. Returns an object
+ * that carries the brand `isMountable` recognises.
+ */
+declare const defineMountable: <Props = unknown, Handle = undefined>(mount: Mountable<Props, Handle>["mount"]) => Mountable<Props, Handle>;
+/** `export const client` of `src/index.ts`: registers the client contributions; the result, if any, runs when the extension is unloaded. */
+type ClientEntry = (client: ClientContext$1) => EntryResult | Promise<EntryResult>;
+/** `export const server = defineServer((server) => { … })`: registers the server contributions. Returns `entry` as is; it only checks the types. */
+declare const defineServer: (entry: ServerEntry$1) => ServerEntry$1;
+/** `export const client = defineClient((client) => { … })`: registers the client contributions. Returns `entry` as is; it only checks the types. */
+declare const defineClient: (entry: ClientEntry) => ClientEntry;
+/** An exercise type registration with `Spec`, `Answer` and `View` inferred from the handlers; pass it to `server.registerExerciseType`. */
+declare const defineExerciseType: <Spec, Answer, View>(registration: ExerciseTypeRegistration<Spec, Answer, View>) => ExerciseTypeRegistration<Spec, Answer, View>;
+//#endregion
+export { MountContext$1 as a, ServerContext$1 as c, defineExerciseType as d, defineMountable as f, InjectionRegistration$1 as i, ServerEntry$1 as l, ClientContext$1 as n, Mountable as o, defineServer as p, ClientEntry as r, PanelRegistration$1 as s, AppApi$1 as t, defineClient as u };