or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

communication.mderror-handling.mdindex.mdlayout-style.mdnativeview.mdregistry.mdutilities.mdwidget-classes.mdwidget-manager.md
tile.json

tessl/npm-jupyter-widgets--base

Foundational classes and utilities for building interactive widgets in Jupyter environments

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@jupyter-widgets/base@6.0.x

To install, run

npx @tessl/cli install tessl/npm-jupyter-widgets--base@6.0.0

index.mddocs/

Jupyter Widgets Base

Jupyter Widgets Base provides the foundational classes, interfaces, and utilities for building interactive widgets in Jupyter environments. This library serves as the core infrastructure that enables the creation of rich, interactive HTML widgets for Jupyter notebooks and IPython kernels.

Package Information

  • Package Name: @jupyter-widgets/base
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @jupyter-widgets/base

Core Imports

import { 
  WidgetModel, 
  DOMWidgetModel, 
  WidgetView, 
  DOMWidgetView,
  IWidgetManager
} from "@jupyter-widgets/base";

For CommonJS:

const { 
  WidgetModel, 
  DOMWidgetModel, 
  WidgetView, 
  DOMWidgetView 
} = require("@jupyter-widgets/base");

Basic Usage

import { WidgetModel, DOMWidgetView, IWidgetManager } from "@jupyter-widgets/base";

// Create a custom widget model
class MyWidgetModel extends WidgetModel {
  defaults() {
    return {
      ...super.defaults(),
      _model_name: 'MyWidgetModel',
      _view_name: 'MyWidgetView',
      value: 0
    };
  }
}

// Create a custom widget view
class MyWidgetView extends DOMWidgetView {
  render() {
    this.el.innerHTML = `<div>Value: ${this.model.get('value')}</div>`;
    
    // Listen for model changes
    this.listenTo(this.model, 'change:value', this.update);
  }
  
  update() {
    this.el.innerHTML = `<div>Value: ${this.model.get('value')}</div>`;
  }
}

// Register with widget manager
const widgetManager: IWidgetManager = /* get widget manager */;
const model = await widgetManager.new_model({
  model_name: 'MyWidgetModel',
  model_module: 'my-widgets',
  model_module_version: '1.0.0'
});

Architecture

Jupyter Widgets Base is built around several key architectural patterns:

  • Model-View Architecture: Clean separation between data (models) and presentation (views) using Backbone.js patterns
  • Communication Layer: Bidirectional communication with Jupyter kernels via comm channels
  • Layout & Style System: Flexible CSS-based layout and styling with trait-based property management
  • Widget Manager: Central registry and factory for widget creation and lifecycle management
  • Lumino Integration: Integration with Lumino widgets for advanced UI capabilities
  • Type Safety: Full TypeScript support with comprehensive type definitions

Capabilities

Core Widget Classes

Foundation classes for building interactive widgets with model-view separation and kernel communication.

class WidgetModel extends Backbone.Model {
  send(content: JSONValue, callbacks?: ICallbacks, buffers?: ArrayBuffer[]): void;
  close(comm_closed?: boolean): Promise<void>;
  get_state(drop_defaults?: boolean): JSONObject;
  save_changes(callbacks?: {}): void;
}

class DOMWidgetModel extends WidgetModel {
  static serializers: ISerializers;
}

class WidgetView extends NativeView<WidgetModel> {
  render(): any;
  update(options?: any): void;
  create_child_view<VT>(child_model: WidgetModel, options?: any): Promise<VT>;
}

class DOMWidgetView extends WidgetView {
  setLayout(layout: LayoutModel, oldLayout?: LayoutModel): void;
  setStyle(style: StyleModel, oldStyle?: StyleModel): void;
  update_classes(old_classes: string[], new_classes: string[], el?: HTMLElement): void;
}

Core Widget Classes

Native View Foundation

Enhanced Backbone.View with native DOM event delegation and element manipulation capabilities.

class NativeView<T extends Backbone.Model> extends Backbone.View<T> {
  delegate(eventName: string, listener: Function): this;
  delegate(eventName: string, selector: string, listener: Function): this;
  undelegate(eventName: string, selector?: string, listener?: Function): this;
  undelegateEvents(): this;
}

Native View Foundation

Widget Manager

Interface and utilities for managing widget lifecycles, creation, and registration within Jupyter environments.

interface IWidgetManager {
  get_model(model_id: string): Promise<WidgetModel>;
  new_model(options: IModelOptions, serialized_state?: JSONObject): Promise<WidgetModel>;
  create_view<VT>(model: WidgetModel, options?: unknown): Promise<VT>;
  callbacks(view?: WidgetView): ICallbacks;
}

interface IModelOptions {
  model_name: string;
  model_module: string;
  model_module_version: string;
  view_name?: string | null;
  view_module?: string | null;
  comm?: any;
  model_id?: string;
}

Widget Manager

Layout & Style System

CSS-based layout and styling system with trait-based property management for responsive widget positioning and appearance.

class LayoutModel extends WidgetModel {
  // Supports CSS properties: width, height, margin, padding, flex, grid, etc.
}

class LayoutView extends WidgetView {
  registerTrait(trait: string): void;
  handleChange(trait: string, value: any): void;
  unlayout(): void;
}

class StyleModel extends WidgetModel {
  static styleProperties: { [s: string]: IStyleProperty };
}

class StyleView extends WidgetView {
  style(): void;
  unstyle(): void;
}

Layout & Style System

Communication

Bidirectional communication layer for kernel integration with message handling and comm channel management.

interface IClassicComm {
  comm_id: string;
  target_name: string;
  send(data: JSONValue, callbacks?: ICallbacks, metadata?: JSONObject): string;
  open(data: JSONValue, callbacks?: ICallbacks, metadata?: JSONObject): string;
  close(data?: JSONValue, callbacks?: ICallbacks, metadata?: JSONObject): string;
}

interface ICallbacks {
  shell?: { [key: string]: (msg: KernelMessage.IShellMessage) => void };
  iopub?: { [key: string]: (msg: KernelMessage.IOPubMessage) => void };
  input?: (msg: KernelMessage.IStdinMessage) => void;
}

Communication

Utilities & Helpers

Utility functions for serialization, buffer handling, view management, and common operations.

function unpack_models(value: any, manager?: IWidgetManager): Promise<WidgetModel | any>;
function pack_models(value: any, widget?: WidgetModel): any;

class ViewList<T> {
  constructor(create_view: (model: any, index: any) => T, remove_view: (view: T) => void, context: any);
  update(new_models: any[]): Promise<T[]>;
  remove(): Promise<void>;
}

function resolvePromisesDict<V>(d: Dict<PromiseLike<V> | V>): Promise<Dict<V>>;
function uuid(): string;
function isEqual(a: unknown, b: unknown): boolean;

Utilities & Helpers

Widget Registry

Registry system for dynamic widget loading and module management.

interface IJupyterWidgetRegistry {
  registerWidget(data: IWidgetRegistryData): void;
}

interface IWidgetRegistryData {
  name: string;
  version: string;
  exports: ExportData;
}

type ExportData = ExportMap | Promise<ExportMap> | (() => ExportMap);

Widget Registry

Error Handling

Error widget components for graceful failure display and debugging support.

function createErrorWidgetModel(error: unknown, msg?: string): typeof WidgetModel;

class ErrorWidgetView extends DOMWidgetView {
  generateErrorMessage(): { msg?: string; stack: string };
  render(): void;
}

function createErrorWidgetView(error?: unknown, msg?: string): typeof WidgetView;

Error Handling

Version Information

The package exports version constants for protocol compatibility:

const JUPYTER_WIDGETS_VERSION = '2.0.0';
const PROTOCOL_VERSION = '2.1.0';