xtralab 0.10.0 → 0.11.0

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;
+  }
+}

package/src/searchReplace/index.ts

@@ -0,0 +1,86 @@
+import {
+  ILabShell,
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { ICommandPalette } from '@jupyterlab/apputils';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+
+const PLUGIN_ID = 'xtralab:search-replace';
+
+const COMMAND_ID = 'xtralab:activate-search-replace';
+
+/**
+ * Widget id of the panel contributed by `jupyterlab-search-replace`. The
+ * extension adds it to the left sidebar but registers no command of its own,
+ * so there is nothing to bind a shortcut to out of the box — this plugin adds
+ * the missing command.
+ */
+const SEARCH_REPLACE_WIDGET_ID = 'jp-search-replace';
+
+/**
+ * Bind Accel+Shift+F (Cmd+Shift+F on macOS, Ctrl+Shift+F elsewhere) to the
+ * project-wide Search and Replace panel, matching the equivalent shortcut in
+ * editors like VS Code.
+ *
+ * Two pieces are needed because that chord is already taken: JupyterLab core
+ * binds Accel+Shift+F to `filebrowser:toggle-main`.
+ *
+ * 1. The chord is freed declaratively. `SettingRegistry.reconcileShortcuts`
+ *    keys collisions and disables on (keys, selector) — not on command — so the
+ *    `@jupyterlab/shortcuts-extension:shortcuts` override in
+ *    `default_setting_overrides.d/00-xtralab.json` disables the file-browser
+ *    binding. The file browser stays reachable from its sidebar tab and the
+ *    View menu; only the keyboard shortcut moves.
+ *
+ * 2. The new binding is added imperatively below rather than as another shipped
+ *    default. A `disabled` default and a re-binding default land on the same
+ *    (keys, selector) slot, and the disable suppresses every default on that
+ *    slot — including the re-binding. `commands.addKeyBinding` runs outside the
+ *    reconcile pass, so it is unaffected and wins cleanly once the file-browser
+ *    binding is gone.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description:
+    'Activate the Search and Replace panel with Accel+Shift+F (Cmd/Ctrl+Shift+F).',
+  autoStart: true,
+  requires: [ILabShell],
+  optional: [ICommandPalette, ITranslator],
+  activate: (
+    app: JupyterFrontEnd,
+    labShell: ILabShell,
+    palette: ICommandPalette | null,
+    translator: ITranslator | null
+  ): void => {
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+    const { commands } = app;
+
+    commands.addCommand(COMMAND_ID, {
+      label: trans.__('Search and Replace'),
+      caption: trans.__('Show the Search and Replace panel'),
+      execute: () => {
+        // `activateById` expands the left sidebar when collapsed, selects the
+        // tab, and the widget focuses its search input from `onAfterShow`, so
+        // the user can start typing a query immediately. It no-ops if
+        // `jupyterlab-search-replace` is unavailable.
+        labShell.activateById(SEARCH_REPLACE_WIDGET_ID);
+      }
+    });
+
+    commands.addKeyBinding({
+      command: COMMAND_ID,
+      keys: ['Accel Shift F'],
+      selector: 'body'
+    });
+
+    if (palette) {
+      palette.addItem({
+        command: COMMAND_ID,
+        category: trans.__('File Operations')
+      });
+    }
+  }
+};
+
+export default plugin;

package/src/showOutput/index.ts

@@ -0,0 +1,199 @@
+import {
+  ILabShell,
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { ICommandPalette } from '@jupyterlab/apputils';
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import type { ReadonlyPartialJSONValue } from '@lumino/coreutils';
+import { Panel } from '@lumino/widgets';
+
+const PLUGIN_ID = 'xtralab:show-output';
+
+/** Render arbitrary rich content into a panel, with no notebook and no kernel. */
+const SHOW_COMMAND = 'xtralab:show';
+
+/**
+ * Parse a JSON-typed value that may have arrived as a string. Agents and the
+ * MCP bridge sometimes serialize a spec (e.g. a Vega-Lite object) to a string;
+ * for `application/...json` MIME types we accept either and parse the string.
+ */
+function coerceData(
+  mimeType: string,
+  data: ReadonlyPartialJSONValue
+): ReadonlyPartialJSONValue {
+  if (typeof data === 'string' && /\+?json$/.test(mimeType)) {
+    try {
+      return JSON.parse(data) as ReadonlyPartialJSONValue;
+    } catch {
+      return data;
+    }
+  }
+  return data;
+}
+
+/**
+ * Contribute `xtralab:show`: render a single MIME bundle into a main-area
+ * panel using the application's render-mime registry.
+ *
+ * This is the kernel-free counterpart to running a notebook. A coding agent
+ * generates the content itself (a Vega-Lite spec, a Markdown explainer, an
+ * HTML fragment, an SVG, a base64 image) and hands it to this command, which
+ * renders it with the same renderers JupyterLab uses for cell output and docks
+ * the result beside the code. Nothing is written to disk and no kernel is
+ * required, so it works even where the kernel has no plotting libraries.
+ *
+ * Repeated calls with the same `id` reuse one panel, so a walkthrough can
+ * refresh the view in place instead of piling up tabs.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description:
+    'Render rich content (Markdown, Vega-Lite, HTML, images) into a 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');
+
+    // One reusable panel per `id`, so repeated shows refresh in place.
+    const panels = new Map<string, Panel>();
+
+    commands.addCommand(SHOW_COMMAND, {
+      label: trans.__('Show Rich Output'),
+      caption: trans.__(
+        'Render Markdown, a Vega-Lite chart, HTML, or an image in a panel'
+      ),
+      describedBy: {
+        args: {
+          type: 'object',
+          required: ['mimeType', 'data'],
+          properties: {
+            mimeType: {
+              type: 'string',
+              description:
+                'MIME type to render, e.g. "text/markdown", "application/vnd.vegalite.v5+json", "text/html", "image/svg+xml", "image/png".'
+            },
+            data: {
+              description:
+                'The content. A string for text/image types (base64 for "image/png"); an object for JSON types such as a Vega-Lite spec.'
+            },
+            label: {
+              type: 'string',
+              description: 'Title for the panel tab. Defaults to "Output".'
+            },
+            id: {
+              type: 'string',
+              description:
+                'Panel identifier. Calls sharing an `id` reuse one panel; defaults to "default".'
+            },
+            area: {
+              type: 'string',
+              description:
+                'Where the panel docks: "right" (default) puts it in the side area so the editor stays full width; "main" puts it in the document area (split with `mode`).'
+            },
+            mode: {
+              type: 'string',
+              description:
+                'Only when `area` is "main": placement relative to the active tab, e.g. "split-right" (default), "split-bottom", "tab-after".'
+            }
+          }
+        }
+      },
+      execute: async args => {
+        const mimeType =
+          typeof args['mimeType'] === 'string' ? args['mimeType'] : undefined;
+        if (!mimeType || args['data'] === undefined) {
+          throw new Error('xtralab:show requires "mimeType" and "data"');
+        }
+        const data = coerceData(mimeType, args['data']);
+        const label =
+          typeof args['label'] === 'string'
+            ? args['label']
+            : trans.__('Output');
+        const id = typeof args['id'] === 'string' ? args['id'] : 'default';
+        const area = args['area'] === 'main' ? 'main' : 'right';
+        const mode =
+          typeof args['mode'] === 'string' ? args['mode'] : 'split-right';
+
+        const bundle = { [mimeType]: data };
+        const chosen = rendermime.preferredMimeType(bundle, 'any');
+        if (!chosen) {
+          throw new Error(
+            `xtralab:show: no renderer for MIME type "${mimeType}"`
+          );
+        }
+
+        const model = rendermime.createModel({ data: bundle, trusted: true });
+        const renderer = rendermime.createRenderer(chosen);
+        // A scrollable Panel, not a MainAreaWidget: MainAreaWidget does not lay
+        // out its content in the side area, and the panel needs to scroll when
+        // the content is taller than it (style/showOutput.css).
+        const widget = new Panel();
+        widget.addClass('jp-xtralab-ShowPanel');
+        widget.id = `xtralab-show-${id}`;
+        widget.title.label = label;
+        widget.title.closable = true;
+        widget.addWidget(renderer);
+
+        // Replace any existing panel with this id so shows refresh in place.
+        const existing = panels.get(id);
+        if (existing && !existing.isDisposed) {
+          existing.dispose();
+        }
+        panels.set(id, widget);
+        widget.disposed.connect(() => {
+          if (panels.get(id) === widget) {
+            panels.delete(id);
+          }
+        });
+
+        // Attach before rendering so renderers that need layout (Vega) size
+        // correctly. Default to the side area so the editor keeps full width;
+        // only split the document area when `area` is "main".
+        if (area === 'main') {
+          labShell.add(widget, 'main', {
+            mode: mode as DocumentMode,
+            activate: true
+          });
+        } else {
+          labShell.add(widget, 'right', { rank: 900 });
+        }
+        // Reveal the panel (the side area does not open from `add` alone).
+        labShell.activateById(widget.id);
+
+        try {
+          await renderer.renderModel(model);
+        } catch (error) {
+          widget.dispose();
+          throw error instanceof Error
+            ? error
+            : new Error(`xtralab:show: failed to render "${mimeType}"`);
+        }
+        return trans.__('Rendered %1 in "%2"', mimeType, label);
+      }
+    });
+
+    if (palette) {
+      palette.addItem({ command: SHOW_COMMAND, category: trans.__('Other') });
+    }
+  }
+};
+
+type DocumentMode =
+  | 'split-top'
+  | 'split-left'
+  | 'split-right'
+  | 'split-bottom'
+  | 'tab-before'
+  | 'tab-after';
+
+export default plugin;