xtralab 0.15.0 → 0.15.2

package/src/git/diffTheme.ts

@@ -26,6 +26,30 @@ registerCustomCSSVariableTheme(JUPYTERLAB_DIFF_THEME, {
   'token-link': 'var(--jp-mirror-editor-link-color)'
 });
 
+/**
+ * `unsafeCSS` for a taller, always-visible horizontal scrollbar. The library
+ * default is 6px and only paints the thumb on hover, in a color close to the
+ * background, so users miss that long lines scroll. Same thumb color as the
+ * app scrollbars in chrome.css.
+ */
+export const DIFF_SCROLLBAR_CSS = `:host {
+  --diffs-scrollbar-gutter-override: 10px;
+  --xtralab-diff-scrollbar-thumb: color-mix(in srgb, var(--jp-ui-font-color1) 28%, transparent);
+}
+[data-code]::-webkit-scrollbar-thumb {
+  background-color: var(--xtralab-diff-scrollbar-thumb);
+  border-width: 2px;
+  border-radius: 999px;
+}
+[data-code]::-webkit-scrollbar-thumb:hover {
+  background-color: color-mix(in srgb, var(--jp-ui-font-color1) 45%, transparent);
+}
+@supports (-moz-appearance: none) {
+  [data-code] {
+    scrollbar-color: var(--xtralab-diff-scrollbar-thumb) transparent;
+  }
+}`;
+
 /**
  * Choose Pierre's palette or the JupyterLab CSS-variable theme.
  */

package/src/git/diffWidget.tsx

@@ -15,19 +15,19 @@ import type { SelectedLineRange } from '@pierre/diffs';
 import type { IAskAgent } from '../askAgent/tokens';
 
 import { buildDiffAskRequest } from './askRequest';
+import {
+  useDiffPreferences,
+  type IDiffPreferences,
+  type ImageDiffViewMode
+} from './diffPreferences';
 import {
   DIFF_WIDGET_CSS_CLASS,
   DiffStyleControl,
   DiffSurface,
+  LineWrapControl,
   NotebookViewModeControl,
   isDarkTheme,
-  isPierreTheme,
-  readStoredDiffStyle,
-  readStoredNotebookViewMode,
-  writeStoredDiffStyle,
-  writeStoredNotebookViewMode,
-  type DiffStyle,
-  type NotebookDiffViewMode
+  isPierreTheme
 } from './diffSurface';
 import { imageDataType } from './imageDiff';
 
@@ -37,8 +37,17 @@ export { DIFF_WIDGET_CSS_CLASS };
  * `Git.Diff.IModel` plus optional xtralab-only metadata.
  */
 export interface IXtralabDiffModel extends Git.Diff.IModel {
+  /**
+   * Whether the file is binary, so no text contents are fetched.
+   */
   isBinary?: boolean;
+  /**
+   * Whether hunks may be discarded; when absent, a working-tree heuristic decides.
+   */
   canDiscard?: boolean;
+  /**
+   * The old-side path when the diff represents a rename.
+   */
   oldFilename?: string;
 }
 
@@ -46,14 +55,31 @@ export interface IXtralabDiffModel extends Git.Diff.IModel {
  * Application-level services the diff model does not carry.
  */
 export interface IXtralabDiffContext {
+  /**
+   * The contents manager used to save hunk-discard results.
+   */
   contentsManager: Contents.IManager;
+  /**
+   * The rendermime registry for rendered notebook diffs, or `null` to
+   * force the textual fallback.
+   */
   rendermime: IRenderMimeRegistry | null;
+  /**
+   * The theme manager used to track theme changes, or `null` to watch
+   * the body attribute instead.
+   */
   themeManager: IThemeManager | null;
   /**
-   * The ask-agent popup; when available, diff line selections get an
-   * "ask an agent about these lines" gutter button.
+   * When available, diff line selections get an "ask an agent" gutter button.
    */
   askAgent: IAskAgent | null;
+  /**
+   * The display choices shared by all diff views.
+   */
+  preferences: IDiffPreferences;
+  /**
+   * The application translation bundle.
+   */
   trans: TranslationBundle;
 }
 
@@ -68,13 +94,14 @@ export class XtralabDiffWidget
     super();
     this._model = model;
     this._context = context;
-    this._notebookViewMode = readStoredNotebookViewMode();
-    this._diffStyle = readStoredDiffStyle();
     // Reuse jupyterlab-git's host sizing while applying xtralab styling.
     this.addClass('jp-git-diff-root');
     this.addClass(DIFF_WIDGET_CSS_CLASS);
   }
 
+  /**
+   * The git diff model being rendered.
+   */
   get model(): Git.Diff.IModel {
     return this._model;
   }
@@ -124,27 +151,16 @@ export class XtralabDiffWidget
     await done.promise;
   }
 
-  get notebookViewMode(): NotebookDiffViewMode {
-    return this._notebookViewMode;
-  }
-
-  setNotebookViewMode(mode: NotebookDiffViewMode): void {
-    if (mode === this._notebookViewMode) {
-      return;
-    }
-    this._notebookViewMode = mode;
-    writeStoredNotebookViewMode(mode);
-    this._notebookViewModeChanged.emit(mode);
-  }
-
-  get notebookViewModeChanged(): ISignal<this, NotebookDiffViewMode> {
-    return this._notebookViewModeChanged;
-  }
-
+  /**
+   * Whether a rendered notebook view is currently available.
+   */
   get hasNotebookView(): boolean {
     return this._hasNotebookView;
   }
 
+  /**
+   * Set whether a rendered notebook view is available.
+   */
   setHasNotebookView(value: boolean): void {
     if (value === this._hasNotebookView) {
       return;
@@ -153,34 +169,23 @@ export class XtralabDiffWidget
     this._hasNotebookViewChanged.emit(value);
   }
 
+  /**
+   * A signal emitted when rendered-notebook availability changes.
+   */
   get hasNotebookViewChanged(): ISignal<this, boolean> {
     return this._hasNotebookViewChanged;
   }
 
-  get diffStyle(): DiffStyle {
-    return this._diffStyle;
-  }
-
-  setDiffStyle(style: DiffStyle): void {
-    if (style === this._diffStyle) {
-      return;
-    }
-    this._diffStyle = style;
-    writeStoredDiffStyle(style);
-    this._diffStyleChanged.emit(style);
-  }
-
-  get diffStyleChanged(): ISignal<this, DiffStyle> {
-    return this._diffStyleChanged;
-  }
-
   /**
-   * Whether the Split/Unified toolbar selector currently applies.
+   * Whether the Split/Unified and line-wrap toolbar controls currently apply.
    */
   get fileDiffActive(): boolean {
     return this._fileDiffActive;
   }
 
+  /**
+   * Set whether the textual file diff is the active view.
+   */
   setFileDiffActive(value: boolean): void {
     if (value === this._fileDiffActive) {
       return;
@@ -189,6 +194,9 @@ export class XtralabDiffWidget
     this._fileDiffActiveChanged.emit(value);
   }
 
+  /**
+   * A signal emitted when {@link fileDiffActive} changes.
+   */
   get fileDiffActiveChanged(): ISignal<this, boolean> {
     return this._fileDiffActiveChanged;
   }
@@ -200,32 +208,49 @@ export class XtralabDiffWidget
     return this._emptied;
   }
 
+  /**
+   * Emit the {@link emptied} signal.
+   */
   notifyEmptied(): void {
     this._emptied.emit();
   }
 
+  /**
+   * Resolve and clear the pending `refresh()` promise, if any.
+   */
   settleRefresh(): void {
     const pending = this._pendingRefresh;
     this._pendingRefresh = null;
     pending?.resolve();
   }
 
+  /**
+   * Dispose of the resources held by the widget.
+   */
   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.
+    // jupyterlab-git awaits refresh() to re-show its diff button; release any
+    // in-flight awaiter so it does not hang on mid-fetch teardown.
     this.settleRefresh();
     super.dispose();
   }
 
+  /**
+   * A counter incremented on each `refresh()` to trigger a content re-fetch.
+   */
   get reloadNonce(): number {
     return this._reloadNonce;
   }
 
+  /**
+   * The application-level services used by the rendered diff.
+   */
   get context(): IXtralabDiffContext {
     return this._context;
   }
 
+  /**
+   * Render the diff view for the current model.
+   */
   protected render(): React.ReactElement {
     return <ModelDiffView widget={this} />;
   }
@@ -234,23 +259,32 @@ export class XtralabDiffWidget
   private _context: IXtralabDiffContext;
   private _reloadNonce = 0;
   private _pendingRefresh: PromiseDelegate<void> | null = null;
-  private _notebookViewMode: NotebookDiffViewMode;
-  private _notebookViewModeChanged = new Signal<this, NotebookDiffViewMode>(
-    this
-  );
   private _hasNotebookView = false;
   private _hasNotebookViewChanged = new Signal<this, boolean>(this);
-  private _diffStyle: DiffStyle;
-  private _diffStyleChanged = new Signal<this, DiffStyle>(this);
   private _fileDiffActive = false;
   private _fileDiffActiveChanged = new Signal<this, boolean>(this);
   private _emptied = new Signal<this, void>(this);
 }
 
+/**
+ * Resolved file-contents state for {@link ModelDiffView}.
+ */
 interface IModelDiffState {
+  /**
+   * Whether the file contents are still being fetched.
+   */
   loading: boolean;
+  /**
+   * The resolved reference-side text.
+   */
   oldText: string;
+  /**
+   * The resolved challenger-side text.
+   */
   newText: string;
+  /**
+   * The fetch error message, or `null` if none.
+   */
   error: string | null;
 }
 
@@ -259,8 +293,15 @@ function ModelDiffView(props: {
 }): React.ReactElement {
   const { widget } = props;
   const model = widget.model as IXtralabDiffModel;
-  const { contentsManager, rendermime, themeManager, askAgent, trans } =
-    widget.context;
+  const {
+    contentsManager,
+    rendermime,
+    themeManager,
+    askAgent,
+    preferences,
+    trans
+  } = widget.context;
+  const values = useDiffPreferences(preferences);
   const nonce = widget.reloadNonce;
 
   const [state, setState] = React.useState<IModelDiffState>({
@@ -270,23 +311,6 @@ function ModelDiffView(props: {
     error: null
   });
 
-  // Mirror toolbar-driven notebook view changes into React state.
-  const [notebookViewMode, setNotebookViewMode] =
-    React.useState<NotebookDiffViewMode>(() => widget.notebookViewMode);
-  React.useEffect(() => {
-    const handler = (
-      sender: XtralabDiffWidget,
-      mode: NotebookDiffViewMode
-    ): void => {
-      setNotebookViewMode(mode);
-    };
-    widget.notebookViewModeChanged.connect(handler);
-    setNotebookViewMode(widget.notebookViewMode);
-    return () => {
-      widget.notebookViewModeChanged.disconnect(handler);
-    };
-  }, [widget]);
-
   const handleNotebookAvailabilityChange = React.useCallback(
     (available: boolean) => {
       widget.setHasNotebookView(available);
@@ -294,20 +318,19 @@ function ModelDiffView(props: {
     [widget]
   );
 
-  // Mirror toolbar-driven diff-style changes into React state.
-  const [diffStyle, setDiffStyle] = React.useState<DiffStyle>(
-    () => widget.diffStyle
+  const handleSplitRatioChange = React.useCallback(
+    (splitRatio: number) => {
+      preferences.update({ splitRatio });
+    },
+    [preferences]
+  );
+
+  const handleImageViewModeChange = React.useCallback(
+    (imageViewMode: ImageDiffViewMode) => {
+      preferences.update({ imageViewMode });
+    },
+    [preferences]
   );
-  React.useEffect(() => {
-    const handler = (sender: XtralabDiffWidget, style: DiffStyle): void => {
-      setDiffStyle(style);
-    };
-    widget.diffStyleChanged.connect(handler);
-    setDiffStyle(widget.diffStyle);
-    return () => {
-      widget.diffStyleChanged.disconnect(handler);
-    };
-  }, [widget]);
 
   const handleFileDiffActiveChange = React.useCallback(
     (active: boolean) => {
@@ -343,14 +366,12 @@ function ModelDiffView(props: {
     };
   }, [themeManager]);
 
-  // Image diffs use the server's base64 payloads; other binaries show a placeholder.
   const isImage = React.useMemo(
     () => imageDataType(model.filename) !== null,
     [model.filename]
   );
   const isBinary = model.isBinary === true && !isImage;
 
-  // Used by the launcher to auto-close an emptied diff after discard.
   const [hunkCount, setHunkCount] = React.useState<number | null>(null);
   const handleMetadataChange = React.useCallback(
     (info: { hunkCount: number | null }) => {
@@ -359,10 +380,8 @@ function ModelDiffView(props: {
     []
   );
 
-  // Fetch both sides whenever the model or reload nonce changes.
   React.useEffect(() => {
     let cancelled = false;
-    // Non-image binaries do not need content fetches.
     if (isBinary) {
       setState({ loading: false, oldText: '', newText: '', error: null });
       // An in-flight `refresh()` still has to resolve.
@@ -399,7 +418,6 @@ function ModelDiffView(props: {
         });
       } finally {
         if (!cancelled) {
-          // Let `refresh()` settle once content has loaded.
           widget.settleRefresh();
         }
       }
@@ -422,7 +440,6 @@ function ModelDiffView(props: {
     }
   }, [state.loading, state.error, isBinary, hunkCount, nonce, widget]);
 
-  // The launcher sets `canDiscard`; jupyterlab-git models fall back to source.
   const canDiscardHunk =
     model.canDiscard ??
     (model.challenger.source === Git.Diff.SpecialRef.WORKING &&
@@ -444,7 +461,6 @@ function ModelDiffView(props: {
         });
       },
       onAfterSave: () => {
-        // Re-pull so the diff reflects the reverted hunk.
         void widget.refresh();
       }
     }),
@@ -481,8 +497,13 @@ function ModelDiffView(props: {
       dark={dark}
       pierreTheme={pierre}
       rendermime={rendermime}
-      notebookViewMode={notebookViewMode}
-      diffStyle={diffStyle}
+      notebookViewMode={values.notebookViewMode}
+      diffStyle={values.diffStyle}
+      lineWrap={values.lineWrap}
+      splitRatio={values.splitRatio}
+      onSplitRatioChange={handleSplitRatioChange}
+      imageViewMode={values.imageViewMode}
+      onImageViewModeChange={handleImageViewModeChange}
       onNotebookAvailabilityChange={handleNotebookAvailabilityChange}
       onFileDiffActiveChange={handleFileDiffActiveChange}
       onMetadataChange={handleMetadataChange}
@@ -503,6 +524,9 @@ class NotebookViewModeToolbarItem extends ReactWidget {
     this.addClass('jp-xtralab-DiffWidget-viewModeToolbarItem');
   }
 
+  /**
+   * Render the Notebook/JSON toggle.
+   */
   protected render(): React.ReactElement {
     return <NotebookViewModeToolbarControl widget={this._widget} />;
   }
@@ -514,38 +538,27 @@ function NotebookViewModeToolbarControl(props: {
   widget: XtralabDiffWidget;
 }): React.ReactElement {
   const { widget } = props;
-  const [mode, setMode] = React.useState<NotebookDiffViewMode>(
-    () => widget.notebookViewMode
-  );
+  const { preferences, trans } = widget.context;
+  const { notebookViewMode } = useDiffPreferences(preferences);
   const [available, setAvailable] = React.useState<boolean>(
     () => widget.hasNotebookView
   );
   React.useEffect(() => {
-    const onMode = (
-      sender: XtralabDiffWidget,
-      next: NotebookDiffViewMode
-    ): void => {
-      setMode(next);
-    };
     const onAvailable = (sender: XtralabDiffWidget, next: boolean): void => {
       setAvailable(next);
     };
-    widget.notebookViewModeChanged.connect(onMode);
     widget.hasNotebookViewChanged.connect(onAvailable);
-    setMode(widget.notebookViewMode);
     setAvailable(widget.hasNotebookView);
     return () => {
-      widget.notebookViewModeChanged.disconnect(onMode);
       widget.hasNotebookViewChanged.disconnect(onAvailable);
     };
   }, [widget]);
 
-  const trans = widget.context.trans;
   return (
     <NotebookViewModeControl
-      mode={mode}
+      mode={notebookViewMode}
       available={available}
-      onChange={next => widget.setNotebookViewMode(next)}
+      onChange={next => preferences.update({ notebookViewMode: next })}
       trans={trans}
     />
   );
@@ -561,6 +574,9 @@ class DiffStyleToolbarItem extends ReactWidget {
     this.addClass('jp-xtralab-DiffWidget-diffStyleToolbarItem');
   }
 
+  /**
+   * Render the Split/Unified toggle.
+   */
   protected render(): React.ReactElement {
     return <DiffStyleToolbarControl widget={this._widget} />;
   }
@@ -572,42 +588,85 @@ function DiffStyleToolbarControl(props: {
   widget: XtralabDiffWidget;
 }): React.ReactElement {
   const { widget } = props;
-  const [style, setStyle] = React.useState<DiffStyle>(() => widget.diffStyle);
-  const [available, setAvailable] = React.useState<boolean>(
-    () => widget.fileDiffActive
+  const { preferences, trans } = widget.context;
+  const { diffStyle, diffStyleControl } = useDiffPreferences(preferences);
+  const available = useFileDiffActive(widget);
+  return (
+    <DiffStyleControl
+      diffStyle={diffStyle}
+      control={diffStyleControl}
+      available={available}
+      onChange={next => preferences.update({ diffStyle: next })}
+      trans={trans}
+    />
   );
-  React.useEffect(() => {
-    const onStyle = (sender: XtralabDiffWidget, next: DiffStyle): void => {
-      setStyle(next);
-    };
-    const onAvailable = (sender: XtralabDiffWidget, next: boolean): void => {
-      setAvailable(next);
-    };
-    widget.diffStyleChanged.connect(onStyle);
-    widget.fileDiffActiveChanged.connect(onAvailable);
-    setStyle(widget.diffStyle);
-    setAvailable(widget.fileDiffActive);
-    return () => {
-      widget.diffStyleChanged.disconnect(onStyle);
-      widget.fileDiffActiveChanged.disconnect(onAvailable);
-    };
-  }, [widget]);
+}
+
+/**
+ * Line-wrap toggle mounted into a host-owned toolbar.
+ */
+class LineWrapToolbarItem extends ReactWidget {
+  constructor(widget: XtralabDiffWidget) {
+    super();
+    this._widget = widget;
+    this.addClass('jp-xtralab-DiffWidget-lineWrapToolbarItem');
+  }
+
+  /**
+   * Render the line-wrap toggle.
+   */
+  protected render(): React.ReactElement {
+    return <LineWrapToolbarControl widget={this._widget} />;
+  }
+
+  private _widget: XtralabDiffWidget;
+}
 
-  const trans = widget.context.trans;
+function LineWrapToolbarControl(props: {
+  widget: XtralabDiffWidget;
+}): React.ReactElement {
+  const { widget } = props;
+  const { preferences, trans } = widget.context;
+  const { lineWrap } = useDiffPreferences(preferences);
+  const available = useFileDiffActive(widget);
   return (
-    <DiffStyleControl
-      diffStyle={style}
+    <LineWrapControl
+      lineWrap={lineWrap}
       available={available}
-      onChange={next => widget.setDiffStyle(next)}
+      onChange={next => preferences.update({ lineWrap: next })}
       trans={trans}
     />
   );
 }
 
+/**
+ * Track {@link XtralabDiffWidget.fileDiffActive} for the split/unified and
+ * line-wrap controls.
+ */
+function useFileDiffActive(widget: XtralabDiffWidget): boolean {
+  const [active, setActive] = React.useState<boolean>(
+    () => widget.fileDiffActive
+  );
+  React.useEffect(() => {
+    const onActive = (sender: XtralabDiffWidget, next: boolean): void => {
+      setActive(next);
+    };
+    widget.fileDiffActiveChanged.connect(onActive);
+    setActive(widget.fileDiffActive);
+    return () => {
+      widget.fileDiffActiveChanged.disconnect(onActive);
+    };
+  }, [widget]);
+  return active;
+}
+
 /**
  * Structural toolbar type shared across host package boundaries.
  */
 interface IDiffToolbar {
+  /**
+   * Add an item to the toolbar under the given name.
+   */
   addItem(name: string, widget: Widget): boolean;
 }
 
@@ -623,4 +682,5 @@ export function addDiffToolbarItems(
     new NotebookViewModeToolbarItem(widget)
   );
   toolbar.addItem('xtralab-diff-style', new DiffStyleToolbarItem(widget));
+  toolbar.addItem('xtralab-diff-line-wrap', new LineWrapToolbarItem(widget));
 }