xtralab 0.10.0 → 0.11.1

package/src/omnibox/index.ts

@@ -0,0 +1,105 @@
+import {
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { ICommandPalette } from '@jupyterlab/apputils';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { Widget } from '@lumino/widgets';
+
+import { IAgentRegistry } from '../launcher/tokens';
+
+import { IOmnibox, OMNIBOX_OPEN_COMMAND } from './tokens';
+import { OmniboxWidget } from './widget';
+
+const PLUGIN_ID = 'xtralab:omnibox';
+
+/**
+ * The omnibox: a single launcher overlay that fuzzy-searches workspace files
+ * (via jupyterlab-quickopen's gitignore-aware endpoint) and JupyterLab
+ * commands, and routes a typed prompt to one of the configured agents (running
+ * it in a fresh terminal through the launcher's `xtralab:start-agent:<id>`
+ * commands). It is opened by the top-bar command bar.
+ *
+ * The agent rows come from the launcher's `IAgentRegistry`; when the launcher
+ * is disabled the omnibox still searches files and commands.
+ */
+const plugin: JupyterFrontEndPlugin<IOmnibox> = {
+  id: PLUGIN_ID,
+  description:
+    'A launcher overlay that searches files and commands and prompts agents.',
+  autoStart: true,
+  provides: IOmnibox,
+  optional: [IAgentRegistry, ICommandPalette, ITranslator],
+  activate: (
+    app: JupyterFrontEnd,
+    agentRegistry: IAgentRegistry | null,
+    palette: ICommandPalette | null,
+    translator: ITranslator | null
+  ): IOmnibox => {
+    const { commands, docRegistry } = app;
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+    const placeholder = trans.__('Search files and commands, or ask an agent…');
+
+    let current: OmniboxWidget | null = null;
+
+    const close = (): void => {
+      const widget = current;
+      current = null;
+      widget?.dispose();
+    };
+
+    const open = (query?: string): void => {
+      // Reopen fresh each time so the input resets and the agent snapshot is
+      // current; the file list is cached separately (see files.ts).
+      close();
+      const widget = new OmniboxWidget({
+        commands,
+        docRegistry,
+        agents: agentRegistry ? agentRegistry.agents : [],
+        placeholder,
+        initialQuery: query ?? '',
+        trans,
+        onClose: close
+      });
+      current = widget;
+      widget.disposed.connect(() => {
+        if (current === widget) {
+          current = null;
+        }
+      });
+      Widget.attach(widget, document.body);
+    };
+
+    commands.addCommand(OMNIBOX_OPEN_COMMAND, {
+      label: trans.__('Search…'),
+      caption: trans.__('Search files and commands, or ask an agent'),
+      execute: args => {
+        // Toggle: a second press (e.g. of the keyboard shortcut) closes it.
+        if (current && !current.isDisposed) {
+          close();
+          return;
+        }
+        const query = args['query'];
+        open(typeof query === 'string' ? query : undefined);
+      }
+    });
+
+    // Open the omnibox with Cmd/Ctrl+K, the common "command center" chord.
+    commands.addKeyBinding({
+      command: OMNIBOX_OPEN_COMMAND,
+      keys: ['Accel K'],
+      selector: 'body'
+    });
+
+    if (palette) {
+      palette.addItem({
+        command: OMNIBOX_OPEN_COMMAND,
+        category: trans.__('Other')
+      });
+    }
+
+    return { open, close };
+  }
+};
+
+export default plugin;

package/src/omnibox/model.ts

@@ -0,0 +1,210 @@
+import type { DocumentRegistry } from '@jupyterlab/docregistry';
+import type { TranslationBundle } from '@jupyterlab/translation';
+import { fileIcon, LabIcon } from '@jupyterlab/ui-components';
+import { StringExt } from '@lumino/algorithm';
+import type { CommandRegistry } from '@lumino/commands';
+
+import type { IAgent } from '../launcher/agents';
+import { agentCommandId } from '../launcher/tokens';
+
+/** The source a result row came from, used to group rows under a header. */
+export type OmniboxItemKind = 'command' | 'file' | 'agent';
+
+/** A single result row, with the action it runs when chosen. */
+export interface IOmniboxItem {
+  kind: OmniboxItemKind;
+  /** Stable React key. */
+  key: string;
+  /** Primary text shown on the row. */
+  label: string;
+  /** Indices of matched characters in `label`, for highlighting. May be empty. */
+  matchIndices: readonly number[];
+  /** Optional secondary text shown trailing the label. */
+  caption?: string;
+  /** Optional leading icon. */
+  icon?: LabIcon;
+  /** Run the row's action. */
+  execute: () => void;
+}
+
+/** Results grouped by source; each group is already capped and sorted. */
+export interface IOmniboxSections {
+  commands: IOmniboxItem[];
+  files: IOmniboxItem[];
+  agents: IOmniboxItem[];
+}
+
+export interface IComputeOptions {
+  query: string;
+  commands: CommandRegistry;
+  docRegistry: DocumentRegistry;
+  agents: IAgent[];
+  files: string[];
+  trans: TranslationBundle;
+}
+
+const COMMAND_LIMIT = 7;
+const FILE_LIMIT = 10;
+
+/**
+ * Prefixes that narrow the search to a single source: a leading `>` to
+ * commands, a leading `/` to files (relative paths never start with `/`, so it
+ * is unambiguous). Without a prefix, every source is searched.
+ */
+const COMMAND_PREFIX = '>';
+const FILE_PREFIX = '/';
+
+type Mode = 'all' | 'commands' | 'files';
+
+/**
+ * Build the grouped result set for a query. A leading `>` searches only
+ * commands and a leading `/` only files; otherwise commands and files are
+ * fuzzy-matched and every prompt-capable agent is offered an "Ask" row
+ * carrying the query as its prompt. An empty term yields no rows (the widget
+ * shows a hint instead).
+ */
+export function computeSections(options: IComputeOptions): IOmniboxSections {
+  const { query, commands, docRegistry, agents, files, trans } = options;
+  const trimmed = query.trim();
+
+  let mode: Mode = 'all';
+  let term = trimmed;
+  if (trimmed.startsWith(COMMAND_PREFIX)) {
+    mode = 'commands';
+    term = trimmed.slice(COMMAND_PREFIX.length).trim();
+  } else if (trimmed.startsWith(FILE_PREFIX)) {
+    mode = 'files';
+    term = trimmed.slice(FILE_PREFIX.length).trim();
+  }
+
+  if (!term) {
+    return { commands: [], files: [], agents: [] };
+  }
+
+  return {
+    commands: mode === 'files' ? [] : matchCommands(commands, term),
+    files:
+      mode === 'commands' ? [] : matchFiles(commands, docRegistry, files, term),
+    // Agents only in the unprefixed view; the prompt is the full typed query.
+    agents: mode === 'all' ? buildAgentItems(commands, agents, term, trans) : []
+  };
+}
+
+function matchCommands(
+  commands: CommandRegistry,
+  term: string
+): IOmniboxItem[] {
+  const query = term.toLowerCase();
+  const scored: Array<{ score: number; item: IOmniboxItem }> = [];
+  for (const id of commands.listCommands()) {
+    let label = '';
+    let visible = true;
+    let caption = '';
+    try {
+      // A command's accessors can throw if they assume a context (e.g. an
+      // active notebook) the omnibox doesn't provide; skip those.
+      label = commands.label(id);
+      visible = commands.isVisible(id);
+      caption = commands.caption(id);
+    } catch {
+      continue;
+    }
+    if (!label || !visible) {
+      continue;
+    }
+    const match = StringExt.matchSumOfSquares(label.toLowerCase(), query);
+    if (!match) {
+      continue;
+    }
+    scored.push({
+      score: match.score,
+      item: {
+        kind: 'command',
+        key: `command:${id}`,
+        label,
+        matchIndices: match.indices,
+        caption: caption || undefined,
+        execute: () => {
+          void commands.execute(id).catch(reason => {
+            console.error(`xtralab omnibox: command "${id}" failed`, reason);
+          });
+        }
+      }
+    });
+  }
+  scored.sort((a, b) => a.score - b.score);
+  return scored.slice(0, COMMAND_LIMIT).map(entry => entry.item);
+}
+
+function matchFiles(
+  commands: CommandRegistry,
+  docRegistry: DocumentRegistry,
+  files: string[],
+  term: string
+): IOmniboxItem[] {
+  const query = term.toLowerCase();
+  const scored: Array<{ score: number; path: string; indices: number[] }> = [];
+  for (const path of files) {
+    const match = StringExt.matchSumOfSquares(path.toLowerCase(), query);
+    if (match) {
+      scored.push({ score: match.score, path, indices: match.indices });
+    }
+  }
+  scored.sort((a, b) => a.score - b.score);
+  return scored.slice(0, FILE_LIMIT).map(({ path, indices }) => ({
+    kind: 'file',
+    key: `file:${path}`,
+    label: path,
+    matchIndices: indices,
+    icon: fileIconForPath(docRegistry, path),
+    execute: () => {
+      void commands.execute('docmanager:open', { path }).catch(reason => {
+        console.error(`xtralab omnibox: failed to open "${path}"`, reason);
+      });
+    }
+  }));
+}
+
+function fileIconForPath(docRegistry: DocumentRegistry, path: string): LabIcon {
+  for (const fileType of docRegistry.getFileTypesForPath(path)) {
+    if (fileType.icon) {
+      return fileType.icon;
+    }
+  }
+  return fileIcon;
+}
+
+function buildAgentItems(
+  commands: CommandRegistry,
+  agents: IAgent[],
+  prompt: string,
+  trans: TranslationBundle
+): IOmniboxItem[] {
+  const items: IOmniboxItem[] = [];
+  for (const agent of agents) {
+    // Agents without `promptArgs` can't take an inline prompt (the launcher
+    // would drop it), so they don't belong in an "Ask …" row.
+    if (agent.promptArgs === undefined) {
+      continue;
+    }
+    items.push({
+      kind: 'agent',
+      key: `agent:${agent.id}`,
+      label: trans.__('Ask %1', agent.label),
+      matchIndices: [],
+      caption: trans.__('Run prompt in a new terminal'),
+      icon: agent.icon,
+      execute: () => {
+        void commands
+          .execute(agentCommandId(agent.id), { prompt })
+          .catch(reason => {
+            console.error(
+              `xtralab omnibox: failed to start agent "${agent.id}"`,
+              reason
+            );
+          });
+      }
+    });
+  }
+  return items;
+}

package/src/omnibox/tokens.ts

@@ -0,0 +1,29 @@
+import { Token } from '@lumino/coreutils';
+
+/**
+ * A launcher overlay that fuzzy-searches across multiple sources — workspace
+ * files, JupyterLab commands — and routes a typed prompt to one of the
+ * configured agents. Provided by `xtralab:omnibox` and consumed (optionally)
+ * by the top-bar command bar, which opens it on click.
+ */
+export interface IOmnibox {
+  /** Open the overlay, optionally seeding the input with `query`. */
+  open(query?: string): void;
+  /** Close the overlay if it is open. */
+  close(): void;
+}
+
+/**
+ * DI token for {@link IOmnibox}. Provided by `xtralab:omnibox`; consumed by
+ * `xtralab:command-bar` so the top-bar pill opens the omnibox.
+ */
+export const IOmnibox = new Token<IOmnibox>(
+  'xtralab:IOmnibox',
+  'Opens the omnibox overlay that searches files and commands and prompts agents.'
+);
+
+/**
+ * Command id that opens the omnibox (registered by `xtralab:omnibox`). Shared
+ * here so the command bar can look up its keybinding and show a shortcut hint.
+ */
+export const OMNIBOX_OPEN_COMMAND = 'xtralab:omnibox:open';

package/src/omnibox/widget.tsx

@@ -0,0 +1,322 @@
+import type { DocumentRegistry } from '@jupyterlab/docregistry';
+import type { TranslationBundle } from '@jupyterlab/translation';
+import { LabIcon, ReactWidget } from '@jupyterlab/ui-components';
+import type { CommandRegistry } from '@lumino/commands';
+import * as React from 'react';
+
+import type { IAgent } from '../launcher/agents';
+
+import { computeSections, IOmniboxItem } from './model';
+import { loadWorkspaceFiles } from './files';
+
+/** DOM id of the results listbox, referenced by the input's `aria-controls`. */
+const LIST_ID = 'jp-xtralab-Omnibox-list';
+
+/** Stable DOM id for the result row at `index`, for `aria-activedescendant`. */
+function optionId(index: number): string {
+  return `jp-xtralab-Omnibox-option-${index}`;
+}
+
+/**
+ * Render `text` with the fuzzy-matched characters at `indices` wrapped in a
+ * highlight span, leaving the rest as plain text.
+ */
+function renderHighlight(
+  text: string,
+  indices: readonly number[]
+): React.ReactNode {
+  if (indices.length === 0) {
+    return text;
+  }
+  const matched = new Set(indices);
+  const nodes: React.ReactNode[] = [];
+  let i = 0;
+  while (i < text.length) {
+    const isMatch = matched.has(i);
+    let j = i;
+    while (j < text.length && matched.has(j) === isMatch) {
+      j++;
+    }
+    const chunk = text.slice(i, j);
+    nodes.push(
+      isMatch ? (
+        <span className="jp-xtralab-Omnibox-match" key={i}>
+          {chunk}
+        </span>
+      ) : (
+        <React.Fragment key={i}>{chunk}</React.Fragment>
+      )
+    );
+    i = j;
+  }
+  return nodes;
+}
+
+function renderIcon(icon?: LabIcon): React.ReactNode {
+  return icon ? (
+    <icon.react tag="span" className="jp-xtralab-Omnibox-itemIcon" />
+  ) : (
+    <span className="jp-xtralab-Omnibox-itemIcon" />
+  );
+}
+
+function OmniboxComponent(props: OmniboxWidget.IOptions): JSX.Element {
+  const {
+    commands,
+    docRegistry,
+    agents,
+    placeholder,
+    initialQuery,
+    trans,
+    onClose
+  } = props;
+  const [query, setQuery] = React.useState(initialQuery);
+  const [files, setFiles] = React.useState<string[]>([]);
+  const [active, setActive] = React.useState(0);
+  const inputRef = React.useRef<HTMLInputElement>(null);
+  const listRef = React.useRef<HTMLDivElement>(null);
+
+  React.useEffect(() => {
+    inputRef.current?.focus();
+  }, []);
+
+  React.useEffect(() => {
+    let cancelled = false;
+    void loadWorkspaceFiles().then(loaded => {
+      if (!cancelled) {
+        setFiles(loaded);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const sections = React.useMemo(
+    () =>
+      computeSections({ query, commands, docRegistry, agents, files, trans }),
+    [query, commands, docRegistry, agents, files, trans]
+  );
+  const flat = React.useMemo(
+    () => [...sections.commands, ...sections.files, ...sections.agents],
+    [sections]
+  );
+  const hasResults = flat.length > 0;
+
+  // Reset the highlighted row whenever the result set changes, and keep the
+  // index in range when results shrink.
+  React.useEffect(() => {
+    setActive(current => (current < flat.length ? current : 0));
+  }, [flat]);
+
+  // Keep the highlighted row scrolled into view as it moves.
+  React.useEffect(() => {
+    listRef.current
+      ?.querySelector('.jp-mod-active')
+      ?.scrollIntoView({ block: 'nearest' });
+  }, [active, flat]);
+
+  const dismiss = React.useCallback(() => {
+    // Defer so unmounting this React root (via onClose) never happens
+    // synchronously inside the event handler that triggered it.
+    window.setTimeout(onClose, 0);
+  }, [onClose]);
+
+  const run = React.useCallback(
+    (item: IOmniboxItem) => {
+      window.setTimeout(() => {
+        onClose();
+        item.execute();
+      }, 0);
+    },
+    [onClose]
+  );
+
+  const onKeyDown = (event: React.KeyboardEvent): void => {
+    switch (event.key) {
+      case 'ArrowDown':
+        event.preventDefault();
+        event.stopPropagation();
+        setActive(current => Math.min(current + 1, flat.length - 1));
+        break;
+      case 'ArrowUp':
+        event.preventDefault();
+        event.stopPropagation();
+        setActive(current => Math.max(current - 1, 0));
+        break;
+      case 'Enter': {
+        event.preventDefault();
+        event.stopPropagation();
+        const item = flat[active];
+        if (item) {
+          run(item);
+        }
+        break;
+      }
+      case 'Escape':
+        event.preventDefault();
+        event.stopPropagation();
+        dismiss();
+        break;
+      default:
+        break;
+    }
+  };
+
+  const renderSection = (
+    title: string,
+    items: IOmniboxItem[],
+    startIndex: number
+  ): React.ReactNode => {
+    if (items.length === 0) {
+      return null;
+    }
+    return (
+      <div
+        className="jp-xtralab-Omnibox-section"
+        role="group"
+        aria-label={title}
+        key={title}
+      >
+        <div className="jp-xtralab-Omnibox-sectionHeader" aria-hidden="true">
+          {title}
+        </div>
+        {items.map((item, offset) => {
+          const index = startIndex + offset;
+          const isActive = index === active;
+          return (
+            <div
+              key={item.key}
+              id={optionId(index)}
+              role="option"
+              aria-selected={isActive}
+              className={
+                'jp-xtralab-Omnibox-item' + (isActive ? ' jp-mod-active' : '')
+              }
+              onMouseEnter={() => setActive(index)}
+              onClick={() => run(item)}
+            >
+              {renderIcon(item.icon)}
+              <span className="jp-xtralab-Omnibox-itemLabel">
+                {renderHighlight(item.label, item.matchIndices)}
+              </span>
+              {item.caption ? (
+                <span className="jp-xtralab-Omnibox-itemCaption">
+                  {item.caption}
+                </span>
+              ) : null}
+            </div>
+          );
+        })}
+      </div>
+    );
+  };
+
+  const filesStart = sections.commands.length;
+  const agentsStart = filesStart + sections.files.length;
+
+  return (
+    <div
+      className="jp-xtralab-Omnibox-overlay"
+      onMouseDown={event => {
+        if (event.target === event.currentTarget) {
+          dismiss();
+        }
+      }}
+    >
+      <div
+        className="jp-xtralab-Omnibox-panel"
+        role="dialog"
+        aria-modal="true"
+        aria-label={placeholder}
+        onMouseDown={event => event.stopPropagation()}
+      >
+        <input
+          ref={inputRef}
+          className="jp-xtralab-Omnibox-input"
+          type="text"
+          spellCheck={false}
+          placeholder={placeholder}
+          aria-label={placeholder}
+          role="combobox"
+          aria-autocomplete="list"
+          aria-expanded={hasResults}
+          aria-controls={LIST_ID}
+          aria-activedescendant={hasResults ? optionId(active) : undefined}
+          value={query}
+          onChange={event => setQuery(event.target.value)}
+          onKeyDown={onKeyDown}
+        />
+        <div
+          className="jp-xtralab-Omnibox-results"
+          id={LIST_ID}
+          role={hasResults ? 'listbox' : undefined}
+          ref={listRef}
+        >
+          {hasResults ? (
+            <>
+              {renderSection(trans.__('Commands'), sections.commands, 0)}
+              {renderSection(trans.__('Files'), sections.files, filesStart)}
+              {renderSection(
+                trans.__('Ask an agent'),
+                sections.agents,
+                agentsStart
+              )}
+            </>
+          ) : (
+            <div className="jp-xtralab-Omnibox-empty">
+              {query.trim()
+                ? trans.__('No matches.')
+                : trans.__(
+                    'Search files and commands, or type a prompt and pick an agent. Prefix with > for commands or / for files.'
+                  )}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * The omnibox overlay widget. Hosts {@link OmniboxComponent} in a React root
+ * attached to `document.body`. It carries `jp-ThemedContainer` so JupyterLab's
+ * theme CSS variables resolve outside the shell, and its own `jp-xtralab-Omnibox`
+ * class for the overlay/panel styling (style/omnibox.css).
+ */
+export class OmniboxWidget extends ReactWidget {
+  constructor(options: OmniboxWidget.IOptions) {
+    super();
+    this._options = options;
+    this.id = 'xtralab-omnibox';
+    this.addClass('jp-xtralab-Omnibox');
+    this.addClass('jp-ThemedContainer');
+  }
+
+  render(): JSX.Element {
+    return <OmniboxComponent {...this._options} />;
+  }
+
+  private _options: OmniboxWidget.IOptions;
+}
+
+/**
+ * A namespace for `OmniboxWidget` statics.
+ */
+export namespace OmniboxWidget {
+  /** Construction options for {@link OmniboxWidget}. */
+  export interface IOptions {
+    commands: CommandRegistry;
+    docRegistry: DocumentRegistry;
+    /** Snapshot of the available agents, read once when the overlay opens. */
+    agents: IAgent[];
+    /** Placeholder text for the input. */
+    placeholder: string;
+    /** Seed text for the input. */
+    initialQuery: string;
+    /** Translation bundle for the overlay's own labels. */
+    trans: TranslationBundle;
+    /** Dismiss the overlay (the plugin disposes the widget). */
+    onClose: () => void;
+  }
+}