feat(types): Make explicit widget_manager interface (#670)

* feat(types): Make explicit widget_manager interface

* chore(anywidget): Make @anywidget/types a dev dependency

* chore: Resync packages

Author: manzt

.changeset/big-guests-cover.md

@@ -0,0 +1,10 @@
+---
+"@anywidget/types": minor
+---
+
+Makes explicit WidgetManager interface
+
+Drops `@jupyter-widgets/base` as a dependency and instead makes an explicit
+interface for `AnyModel.widget_manager`. Right now we only support
+`widget_manager.get_model`, so having the other methods on the interface was
+misleading (leading to issues around `.create_view` not being supported).

package.json

@@ -23,5 +23,5 @@
 		"typescript": "^5.5.4",
 		"vitest": "^2.0.5"
 	},
-	"packageManager": "pnpm@9.4.0"
+	"packageManager": "pnpm@9.9.0"
 }

packages/anywidget/package.json

@@ -20,12 +20,12 @@
 		"build": "node scripts/build.cjs"
 	},
 	"dependencies": {
-		"@anywidget/types": "workspace:~",
 		"@jupyter-widgets/base": "^6",
 		"@lukeed/uuid": "^2.0.1",
 		"solid-js": "^1.8.20"
 	},
 	"devDependencies": {
+		"@anywidget/types": "workspace:^",
 		"@jupyter-widgets/base-manager": "^1.0.11"
 	},
 	"jupyterlab": {

packages/anywidget/src/widget.js

@@ -1,6 +1,11 @@
 import * as uuid from "@lukeed/uuid";
 import * as solid from "solid-js";
 
+/**
+ * @template T
+ * @typedef {T | PromiseLike<T>} Awaitable
+ */
+
 /**
  * @typedef AnyWidget
  * @prop initialize {import("@anywidget/types").Initialize}
@@ -14,7 +19,7 @@ import * as solid from "solid-js";
  */
 
 /**
- * @param {any} condition
+ * @param {unknown} condition
  * @param {string} message
  * @returns {asserts condition}
  */
@@ -192,12 +197,16 @@ function model_proxy(model, context) {
 		off(name, callback) {
 			model.off(name, callback, context);
 		},
+		// @ts-expect-error - the widget_manager type is wider than what
+		// we want to expose to developers.
+		// In a future version, we will expose a more limited API but
+		// that can wait for a minor version bump.
 		widget_manager: model.widget_manager,
 	};
 }
 
 /**
- * @param {void | (() => import('vitest').Awaitable<void>)} fn
+ * @param {void | (() => Awaitable<void>)} fn
  * @param {string} kind
  */
 async function safe_cleanup(fn, kind) {
@@ -320,7 +329,7 @@ class Runtime {
 				console.debug(`[anywidget] esm hot updated: ${id}`);
 				setEsm(model.get("_esm"));
 			});
-			/** @type {void | (() => import("vitest").Awaitable<void>)} */
+			/** @type {void | (() => Awaitable<void>)} */
 			let cleanup;
 			this.#widget_result = solid.createResource(esm, async (update) => {
 				await safe_cleanup(cleanup, "initialize");
@@ -355,7 +364,7 @@ class Runtime {
 	async create_view(view) {
 		let model = view.model;
 		let disposer = solid.createRoot((dispose) => {
-			/** @type {void | (() => import("vitest").Awaitable<void>)} */
+			/** @type {void | (() => Awaitable<void>)} */
 			let cleanup;
 			let resource = solid.createResource(
 				this.#widget_result,

packages/types/index.ts

@@ -1,5 +1,3 @@
-import type { IWidgetManager } from "@jupyter-widgets/base";
-
 type Awaitable<T> = T | Promise<T>;
 type ObjectHash = Record<string, any>;
 type ChangeEventHandler<Payload> = (_: unknown, value: Payload) => void;
@@ -13,6 +11,13 @@ type EventHandler = (...args: any[]) => void;
  */
 type LiteralUnion<T, U = string> = T | (U & {});
 
+interface WidgetManager {
+	/**
+	 * Get a promise for a model by model id.
+	 */
+	get_model<T extends ObjectHash>(model_id: string): Promise<AnyModel<T>>;
+}
+
 export interface AnyModel<T extends ObjectHash = ObjectHash> {
 	get<K extends keyof T>(key: K): T[K];
 	set<K extends keyof T>(key: K, value: T[K]): void;
@@ -41,7 +46,7 @@ export interface AnyModel<T extends ObjectHash = ObjectHash> {
 		callbacks?: any,
 		buffers?: ArrayBuffer[] | ArrayBufferView[],
 	): void;
-	widget_manager: IWidgetManager;
+	widget_manager: WidgetManager;
 }
 
 export type Experimental = {

packages/types/package.json

@@ -14,9 +14,6 @@
 			"import": "./index.ts"
 		}
 	},
-	"dependencies": {
-		"@jupyter-widgets/base": "^6.0.8"
-	},
 	"publishConfig": {
 		"main": "dist/index.js",
 		"types": "dist/index.d.ts",