dev: work towards new UI (#2820)

cspell-words.txt

@@ -82,6 +82,7 @@ stylesheets
 subfolder
 subpath
 textdocument
+todos
 truetype
 tsbuildInfo
 tslib

package.json

@@ -2526,6 +2526,7 @@
     "tools/build-tools",
     "packages/create-disposable",
     "packages/webview-rpc",
+    "packages/webview-api",
     "packages/__cspell-helper",
     "packages/__locale-resolver",
     "packages/__utils",

packages/webview-api/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "webview-api",
+  "version": "1.0.0",
+  "description": "Define the API between the extension and the webviews.",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "vitest run"
+  },
+  "author": "Street Side Software",
+  "license": "MIT",
+  "dependencies": {
+    "create-disposable": "file:../create-disposable",
+    "vscode-jsonrpc": "^8.1.0",
+    "vscode-webview-rpc": "file:../webview-rpc"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}

packages/webview-api/src/__snapshots__/api.test.ts.snap

@@ -0,0 +1,30 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`api > Creating a Server API 1`] = `
+[
+  "clientNotification.onChangeAppState",
+  "serverNotification.showInformationMessage",
+  "serverRequest.getAppState",
+  "serverRequest.resetTodos",
+  "serverRequest.updateAppState",
+  "serverRequest.whatTimeIsIt",
+]
+`;
+
+exports[`api > Creating a Server API 2`] = `
+[
+  "function",
+  "function",
+  "function",
+  "function",
+  "function",
+  "object",
+]
+`;
+
+exports[`api > api 1`] = `
+[
+  "createClientSideHelloWorldApi",
+  "createServerSideHelloWorldApi",
+]
+`;

packages/webview-api/src/__snapshots__/index.test.ts.snap

@@ -0,0 +1,8 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`api > api 1`] = `
+[
+  "createClientSideHelloWorldApi",
+  "createServerSideHelloWorldApi",
+]
+`;

packages/webview-api/src/api.test.ts

@@ -0,0 +1,62 @@
+import { createDisposable } from 'create-disposable';
+import { describe, expect, test, vi } from 'vitest';
+import type { MessageConnection } from 'vscode-jsonrpc';
+
+import type { ClientSideApiDef } from './api';
+import * as api from './api';
+
+describe('api', () => {
+    test('api', () => {
+        expect(Object.keys(api).sort()).toMatchSnapshot();
+    });
+
+    test('Creating a Server API', () => {
+        const connection = getConnection();
+        const clientInterface: ClientSideApiDef = {
+            clientNotifications: {
+                onChangeAppState: true,
+            },
+            clientRequests: {},
+            serverNotifications: {
+                showInformationMessage: true,
+            },
+            serverRequests: {
+                getAppState: true,
+                whatTimeIsIt: true,
+                updateAppState: true,
+                resetTodos: true,
+            },
+        };
+        const client = api.createClientSideHelloWorldApi(connection, clientInterface);
+        expect(client).toBeDefined();
+        const methods = Object.entries(client).flatMap(([key, value]) =>
+            Object.entries(value).map(([k, v]) => [key + '.' + k, v] as const),
+        );
+        const methodMap = Object.fromEntries(methods);
+        expect(Object.keys(methodMap).sort()).toMatchSnapshot();
+        expect(Object.values(methodMap).map((fn) => typeof fn)).toMatchSnapshot();
+    });
+});
+
+function getConnection(): MessageConnection {
+    const c: MessageConnection = {
+        hasPendingResponse: vi.fn(() => false),
+        onClose: vi.fn(() => createDisposable(vi.fn())),
+        onDispose: vi.fn(() => createDisposable(vi.fn())),
+        onError: vi.fn(() => createDisposable(vi.fn())),
+        onNotification: vi.fn(() => createDisposable(vi.fn())),
+        onProgress: vi.fn(() => createDisposable(vi.fn())),
+        onRequest: vi.fn(() => createDisposable(vi.fn())),
+        onUnhandledNotification: vi.fn(() => createDisposable(vi.fn())),
+        onUnhandledProgress: vi.fn(() => createDisposable(vi.fn())),
+        sendNotification: vi.fn(() => Promise.resolve()),
+        sendRequest: vi.fn(() => Promise.resolve()),
+        sendProgress: vi.fn(() => Promise.resolve()),
+        trace: vi.fn(() => Promise.resolve()),
+        listen: vi.fn(),
+        end: vi.fn(),
+        inspect: vi.fn(),
+        dispose: vi.fn(),
+    };
+    return c;
+}

packages/webview-api/src/api.ts

@@ -0,0 +1,56 @@
+import { type MessageConnection } from 'vscode-jsonrpc/lib/common/connection';
+import type {
+    ApplyNotificationAPI,
+    ApplyRequestAPI,
+    ClientAPIDef,
+    ClientSideMethods,
+    RpcAPI,
+    ServerAPIDef,
+    ServerSideMethods,
+} from 'vscode-webview-rpc';
+import { createClientApi, createServerApi } from 'vscode-webview-rpc';
+
+import type { AppState } from './apiModels';
+
+export interface UpdateResult<T> {
+    success: boolean;
+    value: T;
+}
+
+export interface ServerRequestsAPI {
+    whatTimeIsIt(): string;
+    getAppState(): AppState;
+    updateAppState(state: AppState): UpdateResult<AppState>;
+    resetTodos(): void;
+}
+
+export interface ServerNotificationsAPI {
+    showInformationMessage(message: string): void;
+}
+
+export interface ClientRequestsAPI {}
+
+export interface ClientNotificationsAPI {
+    onChangeAppState: (state: AppState) => void;
+}
+
+export interface HelloWorldAPI extends RpcAPI {
+    serverRequests: ApplyRequestAPI<ServerRequestsAPI>;
+    serverNotifications: ApplyNotificationAPI<ServerNotificationsAPI>;
+    clientRequests: ApplyRequestAPI<ClientRequestsAPI>;
+    clientNotifications: ApplyNotificationAPI<ClientNotificationsAPI>;
+}
+
+export interface ServerSideApi extends ServerSideMethods<HelloWorldAPI> {}
+export interface ClientSideApi extends ClientSideMethods<HelloWorldAPI> {}
+
+export type ServerSideApiDef = ServerAPIDef<HelloWorldAPI>;
+export type ClientSideApiDef = ClientAPIDef<HelloWorldAPI>;
+
+export function createServerSideHelloWorldApi(connection: MessageConnection, api: ServerAPIDef<HelloWorldAPI>): ServerSideApi {
+    return createServerApi(connection, api);
+}
+
+export function createClientSideHelloWorldApi(connection: MessageConnection, api: ClientAPIDef<HelloWorldAPI>): ClientSideApi {
+    return createClientApi(connection, api);
+}

packages/webview-api/src/apiModels.ts

@@ -0,0 +1,15 @@
+import type { LogLevel } from 'vscode-webview-rpc';
+
+export interface Todo {
+    uuid: number;
+    done: boolean;
+    text: string;
+}
+
+export type TodoList = Todo[];
+
+export interface AppState {
+    seq: number;
+    todos: TodoList;
+    logLevel: LogLevel;
+}

packages/webview-api/src/index.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, test } from 'vitest';
+
+import * as api from './index';
+
+describe('api', () => {
+    test('api', () => {
+        expect(Object.keys(api).sort()).toMatchSnapshot();
+    });
+});

packages/webview-api/src/index.ts

@@ -0,0 +1 @@
+export { createClientSideHelloWorldApi, createServerSideHelloWorldApi } from './api';

packages/webview-api/tsconfig.json

@@ -0,0 +1,13 @@
+{
+    "extends": "@tsconfig/node18",
+    "compilerOptions": {
+        "outDir": "dist",
+        "lib": ["es2022", "dom"],
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        "rootDir": "./src",
+        "strict": true
+    },
+    "include": ["./src"]
+}

packages/webview-rpc/package.json

@@ -3,15 +3,26 @@
   "private": true,
   "version": "1.0.0",
   "description": "Make JSON-RPC calls to VSCode Webviews",
-  "main": "dist/cjs/index.cjs",
+  "main": "dist/cjs/index.js",
+  "types": "dist/cjs/index.d.ts",
   "type": "commonjs",
   "scripts": {
     "build": "tsc -b tsconfig.json && ts2mjs dist/esm",
     "clean": "shx rm -rf dist",
     "coverage": "jest --coverage",
     "test": "echo ok"
   },
-  "exports": {},
+  "exports": {
+    ".": {
+      "types": "./dist/cjs/index.d.ts",
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/cjs/index.js"
+    },
+    "./webview": {
+      "import": "./dist/esm/webview/index.mjs"
+    },
+    "./extension": "./dist/cjs/extension/index.js"
+  },
   "keywords": [
     "json-rpc",
     "webviews",