Jupyter UI

Jupyter UI provides a set of React.js components that allow developers to build Data Products and Data Platforms compatible with the Jupyter ecosystem. Instead of using iframes to display Jupyter Notebooks, you can manage a full integrated React tree.

The repository is organized into three main packages:

• @datalayer/jupyter-react: Core React components for Jupyter, including Notebook, Cell, Terminal, etc.
• @datalayer/jupyter-lexical: A Lexical editor integration with executable Jupyter cells.
• @datalayer/jupyter-embed: A solution for easy embedding of Jupyter interfaces into any website via HTML data attributes.

The @datalayer/jupyter-react package is the primary library for building Jupyter-compatible interfaces in React. It provides high-level components that wrap JupyterLab's underlying services (kernels, sessions, contents) into a declarative React model.

Key Capabilities:

• Notebook & Cells: Full notebook interface including code/markdown cells and execution.
• Interactive Tools: Integrated Console, Terminal, and FileBrowser.
• Kernel Management: Full control over the kernel lifecycle.
• Output Rendering: Support for plots, widgets, and execution results.
• Collaboration: Plugin-based system for extensible real-time collaboration.

The Jupyter UI Button component provides four distinct visual variants for different interaction contexts:

• Default: Standard button styling.
• Primary: High-emphasis button for main actions.
• Danger: High-alert styling for destructive or critical actions.
• Invisible: Minimalist styling for low-emphasis actions.

Use @datalayer/jupyter-embed to integrate interactive Jupyter components directly into your website or blog. You can embed:

• Code Cells: Interactive Python/Julia/R cells with execution.
• Notebooks: Full Jupyter notebooks with all features.
• Terminals: Interactive terminal sessions.
• Consoles: Jupyter console for REPL-style interaction.
• Outputs: Display pre-computed or executed Jupyter outputs.

The library works by adding a script tag and using HTML elements with data-jupyter-* attributes to define the components.

<!-- Example: A simple interactive cell -->
<div
  data-jupyter-embed="cell"
  data-jupyter-height="200px"
  data-jupyter-auto-execute="true"
>
  <code data-jupyter-source-code> print("Hello from Jupyter!") </code>
</div>

If you need to replicate the look of JupyterLab headings manually, you can use JupyterLab's CSS variables. JupyterLab uses --jp-content-font-family for the font family and --jp-content-font-size# (where # is a range from 0 to 5) for the font size.

Warning: Most JupyterLab font size variables use relative em units. This can cause unexpected scaling issues when nesting elements, as the font size will be calculated relative to the parent's size rather than the root.

<h2
  style={{
    fontFamily: 'var(--jp-content-font-family)',
    fontSize: 'var(--jp-content-font-size1)',
  }}
>
  {'Heading'}
</h2>

The JupyterReactTheme component includes built-in logic for automatic theme management:

1. JupyterLab embedding: If the application is running inside JupyterLab, it automatically syncs with the JupyterLab theme manager.
2. System preferences: When not running in JupyterLab, it respects the browser's prefers-color-scheme setting.
3. Store synchronization: Color mode changes originating from the Jupyter React store are automatically reflected in the UI.

If you only need programmatic access to JupyterLab services (like executing commands or managing notebooks) without rendering the full UI, set the headless prop to true. The UI will be hidden, but the onJupyterLab callback will still provide the adapter for service access.

<JupyterLabApp
  hostId="jupyterlab-headless"
  headless={true}
  onJupyterLab={adapter => {
    // Use adapter for programmatic operations
    // UI is hidden but services are available
  }}
/>

The tool system uses a layered architecture to separate logic from formatting and execution:

1. LLM / User Code: Initiates the request.
2. OperationRunner.execute(): The coordination layer. It manages execution and applies formatting based on the provided context.format.
3. Operation.execute(): The pure logic layer. Operations (like insertCellOperation) perform the core logic and return pure, typed data (e.g., ReadAllCellsResult). They do not handle formatting.
4. Executor.execute(): The platform layer. Implements the actual execution via DefaultExecutor (React/JupyterLab) or BridgeExecutor (VSCode).

This separation ensures that operations remain pure and type-safe, while the runner handles the presentation concerns for different consumers (LLMs vs. Humans).

Jupyter UI manages state through a nested hierarchy of React Context Providers. To ensure all components have access to the server connection, kernels, and notebook state, you must wrap your application in these providers in the following order:

1. JupyterProvider: Manages the server connection and configuration.
2. ServiceManagerProvider: Manages kernels and sessions.
3. NotebookProvider: Manages notebook-specific state.
4. ThemeProvider: Manages visual theming.