xtralab 0.10.0 → 0.11.0

package/src/walkthrough/index.ts

@@ -0,0 +1,202 @@
+import {
+  ILabShell,
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { ICommandPalette } from '@jupyterlab/apputils';
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { tocIcon } from '@jupyterlab/ui-components';
+
+import { IWalkthroughMedia, IWalkthroughStep, WalkthroughPanel } from './panel';
+
+const PLUGIN_ID = 'xtralab:walkthrough';
+
+/** Append a step to the read-only walkthrough panel. */
+const WALKTHROUGH_COMMAND = 'xtralab:walkthrough';
+
+const HIGHLIGHT_LINES_COMMAND = 'xtralab:highlight-lines';
+
+const PANEL_ID = 'xtralab-walkthrough';
+
+/** Pull a `{ mimeType, data }` media object out of a JSON command argument. */
+function readMedia(value: unknown): IWalkthroughMedia | undefined {
+  if (
+    value &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    typeof (value as { mimeType?: unknown }).mimeType === 'string'
+  ) {
+    const media = value as { mimeType: string; data?: unknown };
+    return { mimeType: media.mimeType, data: media.data as never };
+  }
+  return undefined;
+}
+
+function toLine(value: unknown): number | undefined {
+  const n = Math.trunc(Number(value));
+  return Number.isFinite(n) && n >= 1 ? n : undefined;
+}
+
+/**
+ * Contribute `xtralab:walkthrough`: build a persistent, read-only walkthrough
+ * in the right side area instead of narrating only in the agent's chat.
+ *
+ * Each call appends a step (Markdown prose, an optional embedded visual, and an
+ * optional code reference). When a step names a file, the editor follows along
+ * (opening it full-width in the main area, no split) and its lines are
+ * highlighted; the step also keeps a button so the user can jump back to it
+ * later. The panel accumulates the whole tour beside the code, so the user can
+ * read at their own pace rather than chasing the chat.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description: 'Build a read-only guided walkthrough in the side panel.',
+  autoStart: true,
+  requires: [IRenderMimeRegistry, ILabShell],
+  optional: [ICommandPalette, ITranslator],
+  activate: (
+    app: JupyterFrontEnd,
+    rendermime: IRenderMimeRegistry,
+    labShell: ILabShell,
+    palette: ICommandPalette | null,
+    translator: ITranslator | null
+  ): void => {
+    const { commands } = app;
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+
+    let panel: WalkthroughPanel | null = null;
+
+    const ensurePanel = (): WalkthroughPanel => {
+      if (!panel || panel.isDisposed) {
+        panel = new WalkthroughPanel({ rendermime, commands, trans });
+        panel.id = PANEL_ID;
+        panel.title.icon = tocIcon;
+        panel.title.label = trans.__('Walkthrough');
+        panel.title.caption = trans.__('Walkthrough');
+        // Closable so it gets a close button if the user drags it out of the
+        // side area into the main document area. Closing disposes it; the next
+        // xtralab:walkthrough call recreates it back in the side area.
+        panel.title.closable = true;
+        labShell.add(panel, 'right', { rank: 1000, type: 'Walkthrough' });
+        const created = panel;
+        created.disposed.connect(() => {
+          if (panel === created) {
+            panel = null;
+          }
+        });
+      }
+      return panel;
+    };
+
+    commands.addCommand(WALKTHROUGH_COMMAND, {
+      label: trans.__('Add Walkthrough Step'),
+      caption: trans.__('Append a step to the read-only walkthrough panel'),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {
+            title: {
+              type: 'string',
+              description: 'Optional heading for the step.'
+            },
+            body: {
+              type: 'string',
+              description:
+                'Markdown for the step. Renders code snippets, lists, math, and Mermaid diagrams from a ```mermaid fenced block.'
+            },
+            path: {
+              type: 'string',
+              description:
+                'Optional file the step is about, relative to the server root. The editor opens it (full width, no split) and highlights the lines, and the step keeps a button to jump back.'
+            },
+            line: {
+              type: 'number',
+              description: 'First line to highlight (1-indexed).'
+            },
+            endLine: {
+              type: 'number',
+              description: 'Last line to highlight (1-indexed, inclusive).'
+            },
+            media: {
+              type: 'object',
+              description:
+                'Optional embedded visual, e.g. { "mimeType": "application/vnd.vegalite.v5+json", "data": <spec> }.',
+              properties: {
+                mimeType: { type: 'string' },
+                data: {}
+              },
+              required: ['mimeType', 'data']
+            },
+            reveal: {
+              type: 'boolean',
+              description:
+                'Whether to navigate and highlight the code as the step is added. Defaults to true.'
+            },
+            reset: {
+              type: 'boolean',
+              description:
+                'Clear the existing walkthrough before adding this step (start a new tour).'
+            }
+          }
+        }
+      },
+      execute: async args => {
+        const current = ensurePanel();
+        if (args['reset'] === true) {
+          current.clear();
+        }
+
+        const path =
+          typeof args['path'] === 'string' ? args['path'] : undefined;
+        const line = toLine(args['line']);
+        const endLine = toLine(args['endLine']);
+        const media = readMedia(args['media']);
+        const step: IWalkthroughStep = {
+          title: typeof args['title'] === 'string' ? args['title'] : undefined,
+          body: typeof args['body'] === 'string' ? args['body'] : undefined,
+          media,
+          path,
+          line,
+          endLine
+        };
+
+        if (
+          !step.title &&
+          !step.body &&
+          !step.media &&
+          !step.path &&
+          args['reset'] !== true
+        ) {
+          throw new Error(
+            'xtralab:walkthrough needs at least one of: title, body, media, path'
+          );
+        }
+
+        // Reveal the panel, then render the step into it.
+        labShell.activateById(current.id);
+        await current.addStep(step);
+
+        // Let the editor follow the newest step.
+        if (path && args['reveal'] !== false) {
+          await commands.execute(HIGHLIGHT_LINES_COMMAND, {
+            path,
+            line,
+            endLine
+          });
+        }
+
+        return trans.__('Added walkthrough step');
+      }
+    });
+
+    if (palette) {
+      palette.addItem({
+        command: WALKTHROUGH_COMMAND,
+        category: trans.__('Other')
+      });
+    }
+  }
+};
+
+export default plugin;

package/src/walkthrough/panel.ts

@@ -0,0 +1,152 @@
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import type { TranslationBundle } from '@jupyterlab/translation';
+import { fileIcon } from '@jupyterlab/ui-components';
+import type { CommandRegistry } from '@lumino/commands';
+import type { ReadonlyPartialJSONValue } from '@lumino/coreutils';
+import type { Message } from '@lumino/messaging';
+import { Panel, Widget } from '@lumino/widgets';
+
+/** Command the jump links dispatch; keeps the panel decoupled from the plugin. */
+const HIGHLIGHT_LINES_COMMAND = 'xtralab:highlight-lines';
+
+/** A rich visual embedded in a step (rendered through the rendermime registry). */
+export interface IWalkthroughMedia {
+  mimeType: string;
+  data: ReadonlyPartialJSONValue;
+}
+
+/** One step of a walkthrough. Every field is optional, but a step needs at least one. */
+export interface IWalkthroughStep {
+  title?: string;
+  body?: string;
+  media?: IWalkthroughMedia;
+  path?: string;
+  line?: number;
+  endLine?: number;
+}
+
+export namespace WalkthroughPanel {
+  export interface IOptions {
+    rendermime: IRenderMimeRegistry;
+    commands: CommandRegistry;
+    trans: TranslationBundle;
+  }
+}
+
+/**
+ * A read-only, scrollable column of walkthrough steps for the side area.
+ *
+ * The agent appends steps as it narrates, so the explanation lives beside the
+ * code the user is looking at and persists for them to read at their own pace,
+ * rather than scrolling away in the chat. Each step renders Markdown (with code
+ * snippets, Mermaid, math), can embed a rich visual, and can offer a button
+ * that opens the referenced file and highlights its lines.
+ */
+export class WalkthroughPanel extends Panel {
+  constructor(options: WalkthroughPanel.IOptions) {
+    super();
+    this._rendermime = options.rendermime;
+    this._commands = options.commands;
+    this._trans = options.trans;
+    this.addClass('jp-xtralab-Walkthrough');
+  }
+
+  /** Remove every step, leaving an empty panel. */
+  clear(): void {
+    while (this.widgets.length > 0) {
+      this.widgets[0].dispose();
+    }
+  }
+
+  /**
+   * Dispose on close (e.g. the close button when the panel has been dragged to
+   * the main area) rather than leaving a detached, reusable widget behind. The
+   * next `xtralab:walkthrough` call recreates the panel in the side area.
+   */
+  protected onCloseRequest(msg: Message): void {
+    super.onCloseRequest(msg);
+    this.dispose();
+  }
+
+  /** Append a step and scroll it into view. */
+  async addStep(step: IWalkthroughStep): Promise<void> {
+    const card = new Panel();
+    card.addClass('jp-xtralab-Walkthrough-step');
+    this.addWidget(card);
+
+    if (step.title) {
+      const heading = new Widget({ node: document.createElement('h3') });
+      heading.addClass('jp-xtralab-Walkthrough-stepTitle');
+      heading.node.textContent = step.title;
+      card.addWidget(heading);
+    }
+
+    if (step.body) {
+      await this._render(card, 'text/markdown', step.body);
+    }
+
+    if (step.media && typeof step.media.mimeType === 'string') {
+      await this._render(card, step.media.mimeType, step.media.data);
+    }
+
+    if (step.path) {
+      card.addWidget(this._jumpButton(step.path, step.line, step.endLine));
+    }
+
+    // Bring the newest step into view.
+    this.node.scrollTop = this.node.scrollHeight;
+  }
+
+  private async _render(
+    parent: Panel,
+    mimeType: string,
+    data: ReadonlyPartialJSONValue
+  ): Promise<void> {
+    const bundle = { [mimeType]: data };
+    const chosen = this._rendermime.preferredMimeType(bundle, 'any');
+    if (!chosen) {
+      return;
+    }
+    const renderer = this._rendermime.createRenderer(chosen);
+    renderer.addClass('jp-xtralab-Walkthrough-content');
+    parent.addWidget(renderer);
+    await renderer.renderModel(
+      this._rendermime.createModel({ data: bundle, trusted: true })
+    );
+  }
+
+  private _jumpButton(path: string, line?: number, endLine?: number): Widget {
+    const node = document.createElement('div');
+    node.className = 'jp-xtralab-Walkthrough-jumpRow';
+    const where = line ? `${path}:${line}` : path;
+
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'jp-xtralab-Walkthrough-jump';
+    button.title = this._trans.__('Open %1 in the editor', where);
+
+    const icon = fileIcon.element({
+      tag: 'span',
+      className: 'jp-xtralab-Walkthrough-jumpIcon'
+    });
+    const label = document.createElement('span');
+    label.className = 'jp-xtralab-Walkthrough-jumpLabel';
+    label.textContent = where;
+    button.appendChild(icon);
+    button.appendChild(label);
+    node.appendChild(button);
+
+    button.addEventListener('click', () => {
+      void this._commands.execute(HIGHLIGHT_LINES_COMMAND, {
+        path,
+        line,
+        endLine
+      });
+    });
+    return new Widget({ node });
+  }
+
+  private _rendermime: IRenderMimeRegistry;
+  private _commands: CommandRegistry;
+  private _trans: TranslationBundle;
+}

package/style/commandBar.css

@@ -0,0 +1,104 @@
+/* Centered command bar in the top area (xtralab:command-bar). */
+
+/*
+ * The bar is an overlay centered over the whole top panel rather than a flex
+ * item, so its position does not shift with the (variable) width of the menu
+ * bar on its left or the sidebar toggle button on its right. `#jp-top-panel`
+ * is a `.lm-Widget`, which Lumino renders `position: relative`, so this
+ * absolute box is centered against the full width of the top bar.
+ *
+ * `pointer-events: none` here (with `auto` restored on the pill below) keeps
+ * only the pill clickable: the transparent strips above and below it let
+ * clicks fall through to whatever sits beneath the overlay.
+ *
+ * The `z-index` must clear JupyterLab core's settings-driven "Topbar toolbar"
+ * (`#jp-top-bar`, added to the top area at rank 900), which is a `.jp-Toolbar`
+ * at `z-index: 8` that grows to fill the center and paints an opaque
+ * `--jp-toolbar-background`. Sitting one above it lets the centered pill show
+ * through; that toolbar is empty by default, so the overlay covers blank
+ * space rather than hiding any toolbar items.
+ */
+.jp-xtralab-CommandBar {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 50%;
+  z-index: 9;
+  display: flex;
+  align-items: center;
+  transform: translateX(-50%);
+  pointer-events: none;
+}
+
+.jp-xtralab-CommandBar-button {
+  display: flex;
+  flex: 0 0 auto;
+  gap: 6px;
+  align-items: center;
+  width: clamp(160px, 16vw, 220px);
+  height: 20px;
+  padding: 0 8px;
+  margin: 0;
+  overflow: hidden;
+  font-family: var(--jp-ui-font-family);
+  font-size: var(--jp-ui-font-size1);
+  color: var(--jp-ui-font-color2);
+  text-align: left;
+  cursor: pointer;
+
+  /* The theme's input-field fill, so the pill reads as a search box and tracks
+     each theme's input styling across light and dark (a flat layout color is
+     near-black in some dark themes). */
+  background: var(--jp-input-background);
+  border: var(--jp-border-width) solid var(--jp-border-color1);
+  border-radius: 10px;
+  appearance: none;
+  pointer-events: auto;
+}
+
+.jp-xtralab-CommandBar-button:hover {
+  color: var(--jp-ui-font-color1);
+  border-color: var(--jp-border-color0);
+}
+
+.jp-xtralab-CommandBar-button:focus-visible {
+  outline: var(--jp-border-width) solid var(--jp-brand-color1);
+  outline-offset: 1px;
+}
+
+.jp-xtralab-CommandBar-icon {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+}
+
+.jp-xtralab-CommandBar-icon svg {
+  width: 14px;
+  height: 14px;
+}
+
+/* The built-in JupyterLab search icon (@jupyterlab/ui-components) paints with a
+   fixed `jp-icon3` theme gray; override it to currentColor so the magnifier
+   tracks the pill's text color and brightens with the label on hover. */
+.jp-xtralab-CommandBar-button .jp-icon3[fill] {
+  fill: currentcolor;
+}
+
+.jp-xtralab-CommandBar-label {
+  flex: 1 1 auto;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Keyboard-shortcut hint, pushed to the trailing edge by the growing label. */
+.jp-xtralab-CommandBar-shortcut {
+  flex: 0 0 auto;
+  margin-left: 6px;
+  padding: 1px 4px;
+  font-size: var(--jp-ui-font-size0);
+  line-height: 1.2;
+  color: var(--jp-ui-font-color3);
+  border: var(--jp-border-width) solid var(--jp-border-color1);
+  border-radius: 4px;
+}

package/style/highlight.css

@@ -0,0 +1,11 @@
+/*
+ * Line highlight applied by `xtralab:highlight-lines`. The class lands on the
+ * CodeMirror line wrapper (`.cm-line`), so the tint spans the full editor width
+ * and a left accent bar marks the run. The translucent background keeps the
+ * code legible on both light and dark themes.
+ */
+
+.jp-xtralab-highlightLine {
+  background-color: rgb(250 204 21 / 18%);
+  box-shadow: inset 2px 0 0 0 var(--jp-brand-color1);
+}

package/style/index.css

@@ -1,8 +1,13 @@
 @import url('base.css');
+@import url('commandBar.css');
 @import url('editorBreadcrumbs.css');
 @import url('git.css');
+@import url('highlight.css');
 @import url('launcher.css');
+@import url('omnibox.css');
+@import url('showOutput.css');
 @import url('sidebar.css');
 @import url('tabs.css');
 @import url('terminals.css');
 @import url('topBar.css');
+@import url('walkthrough.css');

package/style/index.js

@@ -1,7 +1,12 @@
 import './base.css';
+import './commandBar.css';
 import './git.css';
+import './highlight.css';
 import './launcher.css';
+import './omnibox.css';
+import './showOutput.css';
 import './sidebar.css';
 import './tabs.css';
 import './terminals.css';
 import './topBar.css';
+import './walkthrough.css';

package/style/omnibox.css

@@ -0,0 +1,120 @@
+/* Omnibox overlay (xtralab:omnibox): a centered search box over the shell. */
+
+/*
+ * The widget node is attached to `document.body` (outside the shell) and only
+ * carries theme variables via `jp-ThemedContainer`; the React tree renders the
+ * fixed full-screen overlay below it.
+ */
+.jp-xtralab-Omnibox {
+  position: absolute;
+}
+
+/* Transparent full-viewport layer that centers the panel and catches
+   click-outside to dismiss. */
+.jp-xtralab-Omnibox-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 10001;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+}
+
+.jp-xtralab-Omnibox-panel {
+  display: flex;
+  flex-direction: column;
+  width: min(640px, 92vw);
+  max-height: 60vh;
+  overflow: hidden;
+
+  /* Drop just below the top bar so it reads as a command-center dropdown. */
+  margin-top: calc(var(--jp-private-menubar-height, 28px) + 4px);
+  background: var(--jp-layout-color1);
+  border: var(--jp-border-width) solid var(--jp-border-color1);
+  border-radius: 4px;
+  box-shadow: var(--jp-elevation-z6);
+}
+
+.jp-xtralab-Omnibox-input {
+  padding: 11px 14px;
+  font-family: var(--jp-ui-font-family);
+  font-size: var(--jp-ui-font-size2);
+  color: var(--jp-ui-font-color0);
+  background: transparent;
+  border: none;
+  border-bottom: var(--jp-border-width) solid var(--jp-border-color2);
+  outline: none;
+}
+
+.jp-xtralab-Omnibox-input::placeholder {
+  color: var(--jp-ui-font-color3);
+}
+
+.jp-xtralab-Omnibox-results {
+  padding: 4px 0;
+  overflow-y: auto;
+}
+
+.jp-xtralab-Omnibox-sectionHeader {
+  padding: 6px 14px 2px;
+  font-size: var(--jp-ui-font-size0);
+  font-weight: 600;
+  color: var(--jp-ui-font-color2);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.jp-xtralab-Omnibox-item {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  padding: 5px 14px;
+  font-size: var(--jp-ui-font-size1);
+  color: var(--jp-ui-font-color1);
+  cursor: pointer;
+}
+
+.jp-xtralab-Omnibox-item.jp-mod-active {
+  background: var(--jp-layout-color2);
+}
+
+.jp-xtralab-Omnibox-itemIcon {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  width: 16px;
+  height: 16px;
+}
+
+.jp-xtralab-Omnibox-itemIcon svg {
+  width: 16px;
+  height: 16px;
+}
+
+.jp-xtralab-Omnibox-itemLabel {
+  flex: 1 1 auto;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.jp-xtralab-Omnibox-match {
+  font-weight: 600;
+  color: var(--jp-ui-font-color0);
+}
+
+.jp-xtralab-Omnibox-itemCaption {
+  flex: 0 1 auto;
+  max-width: 45%;
+  overflow: hidden;
+  font-size: var(--jp-ui-font-size0);
+  color: var(--jp-ui-font-color3);
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.jp-xtralab-Omnibox-empty {
+  padding: 14px;
+  font-size: var(--jp-ui-font-size1);
+  color: var(--jp-ui-font-color2);
+}

package/style/showOutput.css

@@ -0,0 +1,11 @@
+/*
+ * The panel `xtralab:show` renders into. It holds a single rendered output and
+ * scrolls when that output is taller (or wider) than the panel, which matters
+ * most in the narrow side area.
+ */
+
+.jp-xtralab-ShowPanel {
+  overflow: auto;
+  padding: 8px;
+  background: var(--jp-layout-color1);
+}