xtralab 0.11.0 → 0.12.0

package/src/git/diffProvider.tsx

@@ -4,8 +4,11 @@ import {
 } from '@jupyterlab/application';
 import { IThemeManager } from '@jupyterlab/apputils';
 import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 import { Git, IGitExtension } from '@jupyterlab/git';
 
+import { IAskAgent } from '../askAgent/tokens';
+
 import {
   IXtralabDiffContext,
   XtralabDiffWidget,
@@ -34,17 +37,22 @@ const diffProviderPlugin: JupyterFrontEndPlugin<void> = {
     "Replaces jupyterlab-git's notebook, text and image diff plugins with xtralab's renderer.",
   autoStart: true,
   requires: [IGitExtension],
-  optional: [IRenderMimeRegistry, IThemeManager],
+  optional: [IRenderMimeRegistry, IThemeManager, ITranslator, IAskAgent],
   activate: (
     app: JupyterFrontEnd,
     gitExtension: IGitExtension,
     rendermime: IRenderMimeRegistry | null,
-    themeManager: IThemeManager | null
+    themeManager: IThemeManager | null,
+    translator: ITranslator | null,
+    askAgent: IAskAgent | null
   ): void => {
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
     const factory = makeXtralabDiffFactory({
       contentsManager: app.serviceManager.contents,
       rendermime,
-      themeManager
+      themeManager,
+      askAgent,
+      trans
     });
 
     // Use one shared factory; the surface detects notebooks/images by filename.

package/src/git/diffSurface.tsx

@@ -2,6 +2,7 @@ import * as React from 'react';
 
 import { IThemeManager } from '@jupyterlab/apputils';
 import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import type { TranslationBundle } from '@jupyterlab/translation';
 import { undoIcon } from '@jupyterlab/ui-components';
 import { FileDiff } from '@pierre/diffs/react';
 import {
@@ -9,7 +10,8 @@ import {
   parseDiffFromFile,
   type DiffLineAnnotation,
   type FileContents,
-  type FileDiffMetadata
+  type FileDiffMetadata,
+  type SelectedLineRange
 } from '@pierre/diffs';
 
 import { ImageDiffView, imageDataType } from './imageDiff';
@@ -197,13 +199,13 @@ export function isPierreTheme(themeManager: IThemeManager | null): boolean {
  * the on-disk path) and triggers any follow-up refresh in
  * {@link IHunkDiscard.onAfterSave}.
  */
-export interface IHunkDiscard {
+interface IHunkDiscard {
   enabled: boolean;
   save: (fullText: string) => Promise<void>;
   onAfterSave: () => void;
 }
 
-export interface IDiffSurfaceProps {
+interface IDiffSurfaceProps {
   /**
    * Whether the host is still resolving the file contents.
    */
@@ -278,6 +280,18 @@ export interface IDiffSurfaceProps {
    * Optional per-hunk discard wiring; omit for a read-only diff.
    */
   hunkDiscard?: IHunkDiscard;
+  /**
+   * When provided, the textual/code file diff gets line selection: clicking
+   * or dragging over the line numbers selects a range, and a gutter "+"
+   * button appears on the hovered/selected lines. Clicking that button
+   * invokes this callback with the selected range and the button's viewport
+   * rectangle (to anchor a popup to), `null` when it cannot be measured.
+   */
+  onLineAsk?: (range: SelectedLineRange, anchor: DOMRect | null) => void;
+  /**
+   * Translation bundle for user-facing strings.
+   */
+  trans: TranslationBundle;
 }
 
 /**
@@ -300,7 +314,9 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
     onNotebookAvailabilityChange,
     onFileDiffActiveChange,
     onMetadataChange,
-    hunkDiscard
+    hunkDiscard,
+    onLineAsk,
+    trans
   } = props;
 
   const hasContent = !loading && error === null && !isBinary;
@@ -432,8 +448,8 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
           <button
             type="button"
             className="jp-xtralab-DiffWidget-hunkButton"
-            title="Discard this hunk's changes"
-            aria-label="Discard hunk"
+            title={trans.__("Discard this hunk's changes")}
+            aria-label={trans.__('Discard hunk')}
             onClick={() => void handleDiscardHunk(hunkIndex)}
           >
             <undoIcon.react
@@ -445,7 +461,26 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
         </div>
       );
     },
-    [handleDiscardHunk]
+    [handleDiscardHunk, trans]
+  );
+
+  const handleGutterUtilityClick = React.useCallback(
+    (range: SelectedLineRange) => {
+      if (onLineAsk === undefined) {
+        return;
+      }
+      // Anchor to the gutter "+" button that was just clicked. It lives in
+      // the `@pierre/diffs` shadow root (which is open), parked on the
+      // hovered/selected line's number element.
+      const slot = wrapperRef.current
+        ?.querySelector('diffs-container')
+        ?.shadowRoot?.querySelector('[data-gutter-utility-slot]');
+      onLineAsk(
+        range,
+        slot instanceof Element ? slot.getBoundingClientRect() : null
+      );
+    },
+    [onLineAsk]
   );
 
   const handleResizerPointerDown = React.useCallback(
@@ -500,8 +535,44 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
     writeStoredSplitRatio(DEFAULT_SPLIT_RATIO);
   }, []);
 
+  const handleResizerKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      const step = event.shiftKey ? 0.1 : 0.01;
+      let next: number | null = null;
+      switch (event.key) {
+        case 'ArrowLeft':
+          next = leftRatioRef.current - step;
+          break;
+        case 'ArrowRight':
+          next = leftRatioRef.current + step;
+          break;
+        case 'Home':
+          next = MIN_SPLIT_RATIO;
+          break;
+        case 'End':
+          next = MAX_SPLIT_RATIO;
+          break;
+      }
+      if (next === null) {
+        return;
+      }
+      event.preventDefault();
+      const clamped = Math.max(
+        MIN_SPLIT_RATIO,
+        Math.min(MAX_SPLIT_RATIO, next)
+      );
+      setLeftRatio(clamped);
+      writeStoredSplitRatio(clamped);
+    },
+    []
+  );
+
   if (loading) {
-    return <div className="jp-xtralab-DiffWidget-status">Loading diff…</div>;
+    return (
+      <div className="jp-xtralab-DiffWidget-status">
+        {trans.__('Loading diff…')}
+      </div>
+    );
   }
   if (error !== null) {
     return (
@@ -513,7 +584,7 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
   if (isBinary) {
     return (
       <div className="jp-xtralab-DiffWidget-status">
-        Binary file — diff not supported.
+        {trans.__('Binary file — diff not supported.')}
       </div>
     );
   }
@@ -527,13 +598,16 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
           reference={oldText}
           challenger={newText}
           fileType={imageType}
+          trans={trans}
         />
       </div>
     );
   }
   if (!showNotebookView && !showFileDiff) {
     return (
-      <div className="jp-xtralab-DiffWidget-status">No content to diff.</div>
+      <div className="jp-xtralab-DiffWidget-status">
+        {trans.__('No content to diff.')}
+      </div>
     );
   }
 
@@ -556,6 +630,7 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
               dark={dark}
               pierreTheme={pierreTheme}
               rendermime={rendermime}
+              trans={trans}
             />
           ) : showFileDiff && metadata !== null ? (
             <FileDiff<IHunkActionAnnotation>
@@ -583,7 +658,17 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
                 // string constant lets the library short-circuit the
                 // re-render path it uses when this option actually
                 // changes.
-                unsafeCSS: SPLIT_RESIZE_CSS
+                unsafeCSS: SPLIT_RESIZE_CSS,
+                // Line selection + the gutter "+" button feed the
+                // ask-agent popup; only wired up when a handler exists so
+                // a plain diff keeps its passive gutter.
+                ...(onLineAsk !== undefined
+                  ? {
+                      enableLineSelection: true,
+                      enableGutterUtility: true,
+                      onGutterUtilityClick: handleGutterUtilityClick
+                    }
+                  : {})
               }}
             />
           ) : null}
@@ -597,9 +682,14 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
             aria-valuenow={Math.round(leftPercent)}
             aria-valuemin={Math.round(MIN_SPLIT_RATIO * 100)}
             aria-valuemax={Math.round(MAX_SPLIT_RATIO * 100)}
-            title="Drag to resize the diff panes (double-click to reset)"
+            aria-label={trans.__('Resize the diff panes')}
+            tabIndex={0}
+            title={trans.__(
+              'Drag to resize the diff panes (double-click to reset)'
+            )}
             onPointerDown={handleResizerPointerDown}
             onDoubleClick={handleResizerDoubleClick}
+            onKeyDown={handleResizerKeyDown}
           />
         ) : null}
       </div>
@@ -617,8 +707,9 @@ export function NotebookViewModeControl(props: {
   mode: NotebookDiffViewMode;
   available: boolean;
   onChange: (mode: NotebookDiffViewMode) => void;
+  trans: TranslationBundle;
 }): React.ReactElement {
-  const { mode, available, onChange } = props;
+  const { mode, available, onChange, trans } = props;
   if (!available) {
     return <></>;
   }
@@ -626,7 +717,7 @@ export function NotebookViewModeControl(props: {
     <div
       className="jp-xtralab-DiffWidget-segmented"
       role="tablist"
-      aria-label="Notebook diff view mode"
+      aria-label={trans.__('Notebook diff view mode')}
     >
       <button
         type="button"
@@ -636,7 +727,7 @@ export function NotebookViewModeControl(props: {
         className="jp-xtralab-DiffWidget-segmentedButton"
         onClick={() => onChange('notebook')}
       >
-        Notebook
+        {trans.__('Notebook')}
       </button>
       <button
         type="button"
@@ -646,7 +737,7 @@ export function NotebookViewModeControl(props: {
         className="jp-xtralab-DiffWidget-segmentedButton"
         onClick={() => onChange('json')}
       >
-        JSON
+        {trans.__('JSON')}
       </button>
     </div>
   );
@@ -700,8 +791,9 @@ export function DiffStyleControl(props: {
   diffStyle: DiffStyle;
   available: boolean;
   onChange: (style: DiffStyle) => void;
+  trans: TranslationBundle;
 }): React.ReactElement {
-  const { diffStyle, available, onChange } = props;
+  const { diffStyle, available, onChange, trans } = props;
   if (!available) {
     return <></>;
   }
@@ -709,7 +801,7 @@ export function DiffStyleControl(props: {
     <div
       className="jp-xtralab-DiffWidget-segmented"
       role="tablist"
-      aria-label="Diff view style"
+      aria-label={trans.__('Diff view style')}
     >
       <button
         type="button"
@@ -717,8 +809,8 @@ export function DiffStyleControl(props: {
         aria-selected={diffStyle === 'split'}
         data-active={diffStyle === 'split'}
         className="jp-xtralab-DiffWidget-segmentedButton jp-xtralab-DiffWidget-segmentedButton-icon"
-        title="Split (side-by-side) view"
-        aria-label="Split view"
+        title={trans.__('Split (side-by-side) view')}
+        aria-label={trans.__('Split view')}
         onClick={() => onChange('split')}
       >
         <DiffSplitIcon />
@@ -729,8 +821,8 @@ export function DiffStyleControl(props: {
         aria-selected={diffStyle === 'unified'}
         data-active={diffStyle === 'unified'}
         className="jp-xtralab-DiffWidget-segmentedButton jp-xtralab-DiffWidget-segmentedButton-icon"
-        title="Unified (inline) view"
-        aria-label="Unified view"
+        title={trans.__('Unified (inline) view')}
+        aria-label={trans.__('Unified view')}
         onClick={() => onChange('unified')}
       >
         <DiffUnifiedIcon />

package/src/git/diffTheme.ts

@@ -6,7 +6,7 @@ import {
 /**
  * Shiki CSS-variable theme used for non-Pierre JupyterLab themes.
  */
-export const JUPYTERLAB_DIFF_THEME: DiffsThemeNames = 'jupyterlab';
+const JUPYTERLAB_DIFF_THEME: DiffsThemeNames = 'jupyterlab';
 
 /**
  * Register a Shiki theme whose token colors read JupyterLab's editor

package/src/git/diffWidget.tsx

@@ -5,11 +5,16 @@ import { PathExt } from '@jupyterlab/coreutils';
 import { Git } from '@jupyterlab/git';
 import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import { Contents } from '@jupyterlab/services';
+import type { TranslationBundle } from '@jupyterlab/translation';
 import { ReactWidget } from '@jupyterlab/ui-components';
 import { PromiseDelegate } from '@lumino/coreutils';
 import { ISignal, Signal } from '@lumino/signaling';
 import { Widget } from '@lumino/widgets';
+import type { SelectedLineRange } from '@pierre/diffs';
 
+import type { IAskAgent } from '../askAgent/tokens';
+
+import { buildDiffAskRequest } from './askRequest';
 import {
   DIFF_WIDGET_CSS_CLASS,
   DiffStyleControl,
@@ -44,6 +49,12 @@ export interface IXtralabDiffContext {
   contentsManager: Contents.IManager;
   rendermime: IRenderMimeRegistry | null;
   themeManager: IThemeManager | null;
+  /**
+   * The ask-agent popup; when available, diff line selections get an
+   * "ask an agent about these lines" gutter button.
+   */
+  askAgent: IAskAgent | null;
+  trans: TranslationBundle;
 }
 
 /**
@@ -103,6 +114,9 @@ export class XtralabDiffWidget
    * Re-pull both sides of the model and re-render.
    */
   async refresh(): Promise<void> {
+    // Settle any refresh still awaiting so a rapid second call cannot orphan
+    // the earlier caller's promise.
+    this.settleRefresh();
     const done = new PromiseDelegate<void>();
     this._pendingRefresh = done;
     this._reloadNonce += 1;
@@ -196,6 +210,14 @@ export class XtralabDiffWidget
     pending?.resolve();
   }
 
+  dispose(): void {
+    // Release any in-flight refresh awaiter so a host that awaits refresh()
+    // (jupyterlab-git re-shows its diff button only once it resolves) does not
+    // hang when the widget is torn down mid-fetch.
+    this.settleRefresh();
+    super.dispose();
+  }
+
   get reloadNonce(): number {
     return this._reloadNonce;
   }
@@ -237,7 +259,8 @@ function ModelDiffView(props: {
 }): React.ReactElement {
   const { widget } = props;
   const model = widget.model as IXtralabDiffModel;
-  const { contentsManager, rendermime, themeManager } = widget.context;
+  const { contentsManager, rendermime, themeManager, askAgent, trans } =
+    widget.context;
   const nonce = widget.reloadNonce;
 
   const [state, setState] = React.useState<IModelDiffState>({
@@ -252,7 +275,7 @@ function ModelDiffView(props: {
     React.useState<NotebookDiffViewMode>(() => widget.notebookViewMode);
   React.useEffect(() => {
     const handler = (
-      _sender: XtralabDiffWidget,
+      sender: XtralabDiffWidget,
       mode: NotebookDiffViewMode
     ): void => {
       setNotebookViewMode(mode);
@@ -276,7 +299,7 @@ function ModelDiffView(props: {
     () => widget.diffStyle
   );
   React.useEffect(() => {
-    const handler = (_sender: XtralabDiffWidget, style: DiffStyle): void => {
+    const handler = (sender: XtralabDiffWidget, style: DiffStyle): void => {
       setDiffStyle(style);
     };
     widget.diffStyleChanged.connect(handler);
@@ -428,6 +451,24 @@ function ModelDiffView(props: {
     [canDiscardHunk, contentsManager, serverPath, widget]
   );
 
+  const handleLineAsk = React.useMemo(() => {
+    if (askAgent === null) {
+      return undefined;
+    }
+    return (range: SelectedLineRange, anchor: DOMRect | null): void => {
+      askAgent.open(
+        buildDiffAskRequest({
+          model,
+          oldText: state.oldText,
+          newText: state.newText,
+          range,
+          anchor,
+          trans
+        })
+      );
+    };
+  }, [askAgent, model, state.oldText, state.newText, trans]);
+
   return (
     <DiffSurface
       loading={state.loading}
@@ -446,6 +487,8 @@ function ModelDiffView(props: {
       onFileDiffActiveChange={handleFileDiffActiveChange}
       onMetadataChange={handleMetadataChange}
       hunkDiscard={hunkDiscard}
+      onLineAsk={handleLineAsk}
+      trans={trans}
     />
   );
 }
@@ -479,12 +522,12 @@ function NotebookViewModeToolbarControl(props: {
   );
   React.useEffect(() => {
     const onMode = (
-      _sender: XtralabDiffWidget,
+      sender: XtralabDiffWidget,
       next: NotebookDiffViewMode
     ): void => {
       setMode(next);
     };
-    const onAvailable = (_sender: XtralabDiffWidget, next: boolean): void => {
+    const onAvailable = (sender: XtralabDiffWidget, next: boolean): void => {
       setAvailable(next);
     };
     widget.notebookViewModeChanged.connect(onMode);
@@ -497,11 +540,13 @@ function NotebookViewModeToolbarControl(props: {
     };
   }, [widget]);
 
+  const trans = widget.context.trans;
   return (
     <NotebookViewModeControl
       mode={mode}
       available={available}
       onChange={next => widget.setNotebookViewMode(next)}
+      trans={trans}
     />
   );
 }
@@ -532,10 +577,10 @@ function DiffStyleToolbarControl(props: {
     () => widget.fileDiffActive
   );
   React.useEffect(() => {
-    const onStyle = (_sender: XtralabDiffWidget, next: DiffStyle): void => {
+    const onStyle = (sender: XtralabDiffWidget, next: DiffStyle): void => {
       setStyle(next);
     };
-    const onAvailable = (_sender: XtralabDiffWidget, next: boolean): void => {
+    const onAvailable = (sender: XtralabDiffWidget, next: boolean): void => {
       setAvailable(next);
     };
     widget.diffStyleChanged.connect(onStyle);
@@ -548,11 +593,13 @@ function DiffStyleToolbarControl(props: {
     };
   }, [widget]);
 
+  const trans = widget.context.trans;
   return (
     <DiffStyleControl
       diffStyle={style}
       available={available}
       onChange={next => widget.setDiffStyle(next)}
+      trans={trans}
     />
   );
 }