xtralab 0.11.0 → 0.12.0

package/src/askAgent/targetPicker.tsx

@@ -0,0 +1,209 @@
+import type { TranslationBundle } from '@jupyterlab/translation';
+import { addIcon, LabIcon } from '@jupyterlab/ui-components';
+import * as React from 'react';
+
+import type { IAgent } from '../launcher/agents';
+
+/**
+ * A running agent terminal offered as a prompt target: the session data
+ * from `IAgentTerminals` plus the matching agent's icon, resolved by the
+ * plugin so these components stay presentation-only.
+ */
+export interface ISessionTarget {
+  /**
+   * The terminal session name.
+   */
+  name: string;
+
+  /**
+   * The session's display label (usually the agent's name).
+   */
+  label: string;
+
+  /**
+   * The agent's latest activity line, when one is available.
+   */
+  activity: string | null;
+
+  /**
+   * The running agent's icon.
+   */
+  icon: LabIcon;
+}
+
+/**
+ * Keyboard support shared by the two radiogroups below, following the ARIA
+ * radio-group pattern: the group is one tab stop (only the checked radio is
+ * tabbable) and the arrow keys move the selection to the neighbouring
+ * radio, wrapping around. Selection follows focus, so the handler clicks
+ * the neighbour and the re-render moves the roving tabindex along.
+ */
+function onRadioGroupKeyDown(event: React.KeyboardEvent<HTMLElement>): void {
+  let delta: number;
+  switch (event.key) {
+    case 'ArrowRight':
+    case 'ArrowDown':
+      delta = 1;
+      break;
+    case 'ArrowLeft':
+    case 'ArrowUp':
+      delta = -1;
+      break;
+    default:
+      return;
+  }
+  const radios = Array.from(
+    event.currentTarget.querySelectorAll<HTMLButtonElement>('[role="radio"]')
+  );
+  const index = radios.findIndex(radio => radio === event.target);
+  if (index === -1) {
+    return;
+  }
+  event.preventDefault();
+  const next = radios[(index + delta + radios.length) % radios.length];
+  next.focus();
+  next.click();
+}
+
+/**
+ * The chip row picking where a prompt goes: "New terminal" plus one chip
+ * per running agent session. Renders nothing while no agent session is
+ * running (a new terminal is then the only possibility and the row would
+ * be noise).
+ */
+export function TargetChips(props: {
+  /**
+   * Agents that could start in a new terminal; gates the "New terminal" chip.
+   */
+  agents: IAgent[];
+  /**
+   * The running agent sessions.
+   */
+  targets: ISessionTarget[];
+  /**
+   * The selected session name, or `null` for a new terminal.
+   */
+  targetName: string | null;
+  trans: TranslationBundle;
+  onSelect: (targetName: string | null) => void;
+}): JSX.Element | null {
+  const { agents, targets, targetName, trans, onSelect } = props;
+  if (targets.length === 0) {
+    return null;
+  }
+  return (
+    <div
+      className="jp-xtralab-AskAgent-targets"
+      role="radiogroup"
+      aria-label={trans.__('Send to')}
+      onKeyDown={onRadioGroupKeyDown}
+    >
+      {agents.length > 0 && (
+        <button
+          type="button"
+          role="radio"
+          aria-checked={targetName === null}
+          tabIndex={targetName === null ? 0 : -1}
+          title={trans.__('Start the agent in a new terminal')}
+          className={
+            'jp-xtralab-AskAgent-targetButton' +
+            (targetName === null ? ' jp-mod-selected' : '')
+          }
+          // Keep focus where the user is typing while picking a target.
+          onMouseDown={event => event.preventDefault()}
+          onClick={() => onSelect(null)}
+        >
+          <addIcon.react
+            tag="span"
+            className="jp-xtralab-AskAgent-targetIcon"
+          />
+          <span className="jp-xtralab-AskAgent-targetLabel">
+            {trans.__('New terminal')}
+          </span>
+        </button>
+      )}
+      {targets.map(target => (
+        <button
+          key={target.name}
+          type="button"
+          role="radio"
+          aria-checked={target.name === targetName}
+          tabIndex={target.name === targetName ? 0 : -1}
+          title={
+            target.activity
+              ? trans.__(
+                  '%1 · %2 — %3',
+                  target.label,
+                  target.name,
+                  target.activity
+                )
+              : trans.__('%1 · %2', target.label, target.name)
+          }
+          className={
+            'jp-xtralab-AskAgent-targetButton' +
+            (target.name === targetName ? ' jp-mod-selected' : '')
+          }
+          onMouseDown={event => event.preventDefault()}
+          onClick={() => onSelect(target.name)}
+        >
+          <target.icon.react
+            tag="span"
+            className="jp-xtralab-AskAgent-targetIcon"
+          />
+          <span className="jp-xtralab-AskAgent-targetLabel">
+            {target.label}
+          </span>
+          <span className="jp-xtralab-AskAgent-targetName">{target.name}</span>
+        </button>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * The icon radiogroup picking which agent a new terminal starts with.
+ * Renders nothing when no agent accepts an initial prompt.
+ */
+export function AgentChoices(props: {
+  agents: IAgent[];
+  agentId: string;
+  trans: TranslationBundle;
+  onSelect: (agentId: string) => void;
+}): JSX.Element | null {
+  const { agents, agentId, trans, onSelect } = props;
+  if (agents.length === 0) {
+    return null;
+  }
+  return (
+    <div
+      className="jp-xtralab-AskAgent-agents"
+      role="radiogroup"
+      aria-label={trans.__('Agent')}
+      onKeyDown={onRadioGroupKeyDown}
+    >
+      {agents.map(agent => (
+        <button
+          key={agent.id}
+          type="button"
+          role="radio"
+          aria-checked={agent.id === agentId}
+          tabIndex={agent.id === agentId ? 0 : -1}
+          title={agent.label}
+          aria-label={agent.label}
+          className={
+            'jp-xtralab-AskAgent-agentButton' +
+            (agent.id === agentId ? ' jp-mod-selected' : '')
+          }
+          // Keep focus where the user is typing while picking an agent.
+          onMouseDown={event => event.preventDefault()}
+          onClick={() => onSelect(agent.id)}
+        >
+          <agent.icon.react
+            tag="span"
+            className="jp-xtralab-AskAgent-agentIcon"
+          />
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/askAgent/tokens.ts

@@ -0,0 +1,139 @@
+import { Token } from '@lumino/coreutils';
+
+/**
+ * The command id that opens the ask-agent popup for the current text-editor
+ * selection. Registered by `xtralab:ask-agent`; exposed here so menus and
+ * other plugins can reference it without importing the plugin internals.
+ */
+export const ASK_AGENT_COMMAND = 'xtralab:ask-agent';
+
+/**
+ * A code location (and optionally the selected source text) that a prompt
+ * should point an agent at. The structured fields are composed into the
+ * final prompt by the ask-agent plugin so every entry point — editor
+ * selection, diff line selection — produces consistently worded prompts.
+ */
+export interface IAskAgentContext {
+  /**
+   * Path of the file the selection belongs to, relative to {@link cwd} (or
+   * to the server root when no cwd is given) so the launched agent can open
+   * it directly.
+   */
+  path: string;
+
+  /**
+   * Server-relative directory the agent's terminal starts in. Omit to start
+   * in the server root. Diff selections pass the git repository root here so
+   * the agent can run git commands right away.
+   */
+  cwd?: string;
+
+  /**
+   * The notebook cell the selection lives in, when {@link path} is a
+   * notebook. `index` is the cell's 0-based position in the nbformat
+   * `cells` array; `type` is the nbformat cell type (`code`, `markdown`,
+   * `raw`). When set, {@link startLine}/{@link endLine} count within the
+   * cell's source rather than within a file.
+   */
+  cell?: {
+    index: number;
+    type: string;
+  };
+
+  /**
+   * First selected line, 1-indexed and inclusive. Omit when no line range is
+   * known (the prompt then only references the file).
+   */
+  startLine?: number;
+
+  /**
+   * Last selected line, 1-indexed and inclusive. Defaults to
+   * {@link startLine} when omitted.
+   */
+  endLine?: number;
+
+  /**
+   * Whether {@link startLine}/{@link endLine} index the file's current
+   * working-tree content. `false` for diff selections taken from another
+   * revision (the old side, or a challenger that is not the working tree),
+   * whose numbers must not be used to highlight the working file. Omitted
+   * means `true`.
+   */
+  linesInWorkingFile?: boolean;
+
+  /**
+   * The selected source text. May be empty when only a location is known;
+   * the prompt then relies on the path and line range alone.
+   */
+  text: string;
+
+  /**
+   * Extra agent-facing locator appended after the line range in the prompt,
+   * e.g. `the old side (INDEX) of the git diff`. Written in English because
+   * it is consumed by the agent, not shown in the UI.
+   */
+  location?: string;
+
+  /**
+   * Short user-facing tag shown in the popup header next to the file name,
+   * e.g. "old version". Translated, unlike {@link location}. Omit when the
+   * range reads naturally as the file's current content.
+   */
+  note?: string;
+}
+
+/**
+ * Where a submitted prompt goes: a fresh terminal started with the chosen
+ * agent's command, or an existing terminal session whose running agent
+ * receives the prompt in its input box (queued by the agent itself when it
+ * is busy).
+ */
+export type AskAgentTarget =
+  | { kind: 'new'; agentId: string }
+  | { kind: 'session'; name: string };
+
+/**
+ * A request to open the ask-agent popup: what code to prompt about and
+ * where to place the popup on screen.
+ */
+export interface IAskAgentRequest {
+  /**
+   * The code location and selection the prompt is about.
+   */
+  context: IAskAgentContext;
+
+  /**
+   * Viewport rectangle the popup anchors to (typically the selection end or
+   * the button that was clicked). `null` positions the popup near the top
+   * center of the viewport.
+   */
+  anchor: DOMRect | null;
+}
+
+/**
+ * The ask-agent popup: a small floating prompt box that sends the given
+ * code selection, plus the user's typed instruction, to one of the
+ * configured coding agents — in a fresh terminal, or into an agent already
+ * running in an existing one.
+ */
+export interface IAskAgent {
+  /**
+   * Open the popup for `request`, replacing any popup already open.
+   */
+  open(request: IAskAgentRequest): void;
+
+  /**
+   * Close the popup if it is open.
+   */
+  close(): void;
+}
+
+/**
+ * DI token for {@link IAskAgent}. Provided by `xtralab:ask-agent` and
+ * consumed — optionally, so diffs still render when the plugin is disabled —
+ * by the git diff plugins to offer "ask an agent about these lines".
+ */
+export const IAskAgent = new Token<IAskAgent>(
+  'xtralab:IAskAgent',
+  'A floating prompt box that sends the current code selection to a coding agent running in a terminal.'
+);

package/src/commandBar/index.ts

@@ -1,8 +1,8 @@
 import {
-  ILabShell,
   JupyterFrontEnd,
   JupyterFrontEndPlugin
 } from '@jupyterlab/application';
+import { IToolbarWidgetRegistry } from '@jupyterlab/apputils';
 import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 import { searchIcon } from '@jupyterlab/ui-components';
 import { CommandRegistry } from '@lumino/commands';
@@ -13,15 +13,24 @@ import { IOmnibox, OMNIBOX_OPEN_COMMAND } from '../omnibox/tokens';
 const PLUGIN_ID = 'xtralab:command-bar';
 
 /**
- * A search-bar-styled launcher for the `top` area. It holds no text input of
- * its own: clicking the pill (or pressing Enter/Space while it is focused)
- * runs `onActivate`, which opens the omnibox.
- *
- * The widget's root is a transparent, full-height wrapper centered as an
- * overlay over the whole top panel (style/commandBar.css). The wrapper
- * ignores pointer events so only the inner pill is clickable and the empty
- * strips above and below it let clicks fall through to whatever sits beneath
- * the overlay, such as the menu bar.
+ * Factory name of JupyterLab's settings-driven top bar toolbar (`#jp-top-bar`,
+ * built by `@jupyterlab/application-extension:top-bar`).
+ */
+const TOPBAR_FACTORY = 'TopBar';
+
+/**
+ * Name of the pill item within that toolbar. Its placement is declared under
+ * `jupyter.lab.toolbars` in this plugin's settings schema
+ * (schema/command-bar.json): the core toolbar ships a spacer at rank 50, so
+ * the pill's higher rank lands it at the trailing end of the toolbar, next to
+ * the right-sidebar toggle button.
+ */
+const ITEM_NAME = 'omnibox';
+
+/**
+ * A search-bar-styled launcher pill. It holds no text input of its own:
+ * clicking it (or pressing Enter/Space while it is focused) runs `onActivate`,
+ * which opens the omnibox.
  */
 class CommandBar extends Widget {
   constructor(options: CommandBar.IOptions) {
@@ -43,9 +52,9 @@ class CommandBar extends Widget {
   }
 
   protected onAfterAttach(): void {
-    // The pill restores `pointer-events: auto`, so the click bubbles from it
-    // up to the root node listened on here; keyboard Enter/Space on the
-    // focused button raises the same synthetic click.
+    // The click bubbles from the inner pill button up to the root node
+    // listened on here; keyboard Enter/Space on the focused button raises the
+    // same synthetic click.
     this.node.addEventListener('click', this);
   }
 
@@ -58,13 +67,21 @@ class CommandBar extends Widget {
 
 namespace CommandBar {
   export interface IOptions {
-    /** Placeholder-style text shown inside the pill. */
+    /**
+     * Placeholder-style text shown inside the pill.
+     */
     label: string;
-    /** Tooltip and accessible name for the button. */
+    /**
+     * Tooltip and accessible name for the button.
+     */
     caption: string;
-    /** Formatted keyboard shortcut shown as a trailing hint, if any. */
+    /**
+     * Formatted keyboard shortcut shown as a trailing hint, if any.
+     */
     shortcut?: string;
-    /** Runs on click or keyboard activation. */
+    /**
+     * Runs on click or keyboard activation.
+     */
     onActivate: () => void;
   }
 
@@ -73,6 +90,10 @@ namespace CommandBar {
     caption: string,
     shortcut?: string
   ): HTMLElement {
+    // The root is a plain wrapper: as a toolbar item it receives the core
+    // `.jp-Toolbar > .jp-Toolbar-item` sizing (full height, centered flex),
+    // which would otherwise stretch the pill itself; the button inside keeps
+    // its own compact pill height.
     const wrapper = document.createElement('div');
 
     const button = document.createElement('button');
@@ -108,26 +129,30 @@ namespace CommandBar {
 }
 
 /**
- * Add a centered, search-bar-styled command bar to the top area. Clicking it
- * opens the omnibox — a launcher overlay that fuzzy-searches files and
- * commands and routes a typed prompt to an agent (the leading sidebar toggle
- * and the menu bar sit to its left, the trailing sidebar toggle to its right;
- * the bar is centered over the whole panel as an overlay, so it stays put
- * regardless of their widths).
+ * Contribute a search-bar-styled command bar to JupyterLab's top bar toolbar.
+ * Clicking it opens the omnibox — a launcher overlay that fuzzy-searches files
+ * and commands and routes a typed prompt to an agent.
  *
- * The bar is only added when the omnibox is available — the `IOmnibox` token
- * is provided by `xtralab:omnibox` — so it never appears with nothing to open.
+ * The pill is a regular settings-driven toolbar item: this plugin registers a
+ * widget factory for it on the `IToolbarWidgetRegistry` and declares its rank
+ * in schema/command-bar.json, so users can move or disable it from the Top
+ * Bar settings like any other toolbar item.
+ *
+ * The factory is only registered when the omnibox is available — the
+ * `IOmnibox` token is provided by `xtralab:omnibox` — so the pill never
+ * appears with nothing to open (without a factory, the toolbar item resolves
+ * to an empty command button that renders nothing).
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
   description:
-    'Add a centered command bar to the top area that opens the omnibox.',
+    'Add a command bar to the top bar toolbar that opens the omnibox.',
   autoStart: true,
-  requires: [ILabShell],
+  requires: [IToolbarWidgetRegistry],
   optional: [IOmnibox, ITranslator],
   activate: (
     app: JupyterFrontEnd,
-    labShell: ILabShell,
+    toolbarRegistry: IToolbarWidgetRegistry,
     omnibox: IOmnibox | null,
     translator: ITranslator | null
   ): void => {
@@ -137,28 +162,29 @@ const plugin: JupyterFrontEndPlugin<void> = {
 
     const trans = (translator ?? nullTranslator).load('jupyterlab');
 
-    // Show the omnibox's keyboard shortcut as a hint in the pill, derived from
-    // the live binding (registered by xtralab:omnibox, which activates first as
-    // the IOmnibox provider) so it stays correct and uses the platform's
-    // modifier symbols. Empty when no binding is registered.
-    const binding = app.commands.keyBindings.find(
-      keyBinding => keyBinding.command === OMNIBOX_OPEN_COMMAND
-    );
-    const shortcut = binding
-      ? CommandRegistry.formatKeystroke(binding.keys)
-      : '';
-
-    const widget = new CommandBar({
-      label: trans.__('Search…'),
-      caption: trans.__('Search files and commands, or ask an agent'),
-      shortcut,
-      onActivate: () => {
-        omnibox.open();
-      }
+    toolbarRegistry.addFactory(TOPBAR_FACTORY, ITEM_NAME, () => {
+      // Show the omnibox's keyboard shortcut as a hint in the pill, derived
+      // from the live binding (registered by xtralab:omnibox, which activates
+      // first as the IOmnibox provider) so it stays correct and uses the
+      // platform's modifier symbols. Empty when no binding is registered.
+      const binding = app.commands.keyBindings.find(
+        keyBinding => keyBinding.command === OMNIBOX_OPEN_COMMAND
+      );
+      const shortcut = binding
+        ? CommandRegistry.formatKeystroke(binding.keys)
+        : '';
+
+      const widget = new CommandBar({
+        label: trans.__('Search…'),
+        caption: trans.__('Search files and commands, or ask an agent'),
+        shortcut,
+        onActivate: () => {
+          omnibox.open();
+        }
+      });
+      widget.id = 'xtralab-command-bar';
+      return widget;
     });
-    widget.id = 'xtralab-command-bar';
-
-    labShell.add(widget, 'top', { rank: 500 });
   }
 };
 

package/src/editorBreadcrumbs/index.ts

@@ -6,6 +6,11 @@ import type {
   DocumentRegistry,
   IDocumentWidget
 } from '@jupyterlab/docregistry';
+import {
+  ITranslator,
+  nullTranslator,
+  type TranslationBundle
+} from '@jupyterlab/translation';
 import type { CommandRegistry } from '@lumino/commands';
 import { DisposableDelegate, type IDisposable } from '@lumino/disposable';
 import type { Widget } from '@lumino/widgets';
@@ -20,8 +25,9 @@ class EditorBreadcrumbsExtension implements DocumentRegistry.IWidgetExtension<
   IDocumentWidget<Widget, DocumentRegistry.IModel>,
   DocumentRegistry.IModel
 > {
-  constructor(commands: CommandRegistry) {
+  constructor(commands: CommandRegistry, trans: TranslationBundle) {
     this._commands = commands;
+    this._trans = trans;
   }
 
   createNew(
@@ -30,7 +36,8 @@ class EditorBreadcrumbsExtension implements DocumentRegistry.IWidgetExtension<
   ): IDisposable | void {
     const breadcrumbs = new EditorBreadcrumbs({
       context,
-      commands: this._commands
+      commands: this._commands,
+      trans: this._trans
     });
     const added = widget.toolbar.insertItem(0, TOOLBAR_ITEM_NAME, breadcrumbs);
 
@@ -45,6 +52,7 @@ class EditorBreadcrumbsExtension implements DocumentRegistry.IWidgetExtension<
   }
 
   private _commands: CommandRegistry;
+  private _trans: TranslationBundle;
 }
 
 /**
@@ -59,10 +67,12 @@ const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
   description: 'Display the active file path in text editor toolbars.',
   autoStart: true,
-  activate: (app: JupyterFrontEnd): void => {
+  optional: [ITranslator],
+  activate: (app: JupyterFrontEnd, translator: ITranslator | null): void => {
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
     app.docRegistry.addWidgetExtension(
       EDITOR_FACTORY,
-      new EditorBreadcrumbsExtension(app.commands)
+      new EditorBreadcrumbsExtension(app.commands, trans)
     );
   }
 };

package/src/editorBreadcrumbs/widget.ts

@@ -1,5 +1,6 @@
 import { PageConfig } from '@jupyterlab/coreutils';
 import type { DocumentRegistry } from '@jupyterlab/docregistry';
+import type { TranslationBundle } from '@jupyterlab/translation';
 import { homeIcon as rootIcon } from '@jupyterlab/ui-components';
 import type { CommandRegistry } from '@lumino/commands';
 import { Widget } from '@lumino/widgets';
@@ -19,26 +20,24 @@ const SEPARATOR_CLASS = 'jp-BreadCrumbs-separator';
  */
 const REVEAL_COMMAND = 'xtralab:reveal-path';
 
-export interface IEditorBreadcrumbsOptions {
+interface IEditorBreadcrumbsOptions {
   context: DocumentRegistry.IContext<DocumentRegistry.IModel>;
   commands: CommandRegistry;
+  trans: TranslationBundle;
 }
 
 /**
- * Read-only breadcrumb path for file editor toolbars.
- *
- * The upstream `@jupyterlab/filebrowser` BreadCrumbs widget is coupled to
- * FileBrowserModel navigation, drag/drop, and path editing. If that code
- * becomes reusable upstream, replace this local display-only renderer with
- * the shared implementation.
+ * Read-only breadcrumb path for file editor toolbars: renders the open
+ * file's path as clickable segments, each dispatching the reveal command.
  */
 export class EditorBreadcrumbs extends Widget {
   constructor(options: IEditorBreadcrumbsOptions) {
     super({ node: document.createElement('nav') });
     this._context = options.context;
     this._commands = options.commands;
+    this._trans = options.trans;
     this.addClass(EDITOR_BREADCRUMBS_CLASS);
-    this.node.setAttribute('aria-label', 'Editor file path');
+    this.node.setAttribute('aria-label', this._trans.__('Editor file path'));
 
     this._container = document.createElement('span');
     this._container.className = BREADCRUMBS_CONTAINER_CLASS;
@@ -105,7 +104,9 @@ export class EditorBreadcrumbs extends Widget {
     const item = rootIcon.element({
       className: ROOT_CLASS,
       tag: 'span',
-      title: PageConfig.getOption('serverRoot') || 'Jupyter Server Root',
+      title:
+        PageConfig.getOption('serverRoot') ||
+        this._trans.__('Jupyter Server Root'),
       stylesheet: 'breadCrumb'
     });
     item.dataset.path = '/';
@@ -153,6 +154,7 @@ export class EditorBreadcrumbs extends Widget {
 
   private _context: DocumentRegistry.IContext<DocumentRegistry.IModel>;
   private _commands: CommandRegistry;
+  private _trans: TranslationBundle;
   private _container: HTMLElement;
   private _content: HTMLElement;
 }