xtralab 0.15.0 → 0.15.2

package/src/git/commands.ts

@@ -10,6 +10,7 @@ import { ISignal, Signal } from '@lumino/signaling';
 import type { IAskAgent } from '../askAgent/tokens';
 import { getTreeIcon } from '../fileBrowser/icons';
 import { fileChangeToDiffModel } from './diffModel';
+import type { IDiffPreferences } from './diffPreferences';
 import {
   DIFF_WIDGET_CSS_CLASS,
   XtralabDiffWidget,
@@ -28,16 +29,25 @@ export namespace CommandIDs {
  * Argument shapes used by {@link CommandIDs.openDiff}.
  */
 export namespace CommandArguments {
+  /**
+   * The arguments for the open-diff command.
+   */
   export interface IOpenDiff {
+    /**
+     * The server-relative path of the repository containing the change.
+     */
     repoPath: string;
+    /**
+     * The file change to show.
+     */
     change: IFileChange;
+    /**
+     * Whether to open the diff as a pinned tab instead of the shared preview.
+     */
     pin?: boolean;
   }
 }
 
-/**
- * Widget id of the single, reused preview diff tab.
- */
 export const PREVIEW_DIFF_WIDGET_ID = 'xtralab:diff:preview';
 
 /**
@@ -70,14 +80,23 @@ export class DiffMainAreaWidget extends MainAreaWidget<XtralabDiffWidget> {
     this._trans = trans;
   }
 
+  /**
+   * The file change currently displayed.
+   */
   get change(): IFileChange {
     return this._change;
   }
 
+  /**
+   * Whether the widget is pinned rather than the shared preview.
+   */
   get pinned(): boolean {
     return this._pinned;
   }
 
+  /**
+   * Pin the widget; a no-op when already pinned.
+   */
   pin(): void {
     if (this._pinned) {
       return;
@@ -86,10 +105,16 @@ export class DiffMainAreaWidget extends MainAreaWidget<XtralabDiffWidget> {
     this._pinnedChanged.emit(true);
   }
 
+  /**
+   * A signal emitted when the widget becomes pinned.
+   */
   get pinnedChanged(): ISignal<this, boolean> {
     return this._pinnedChanged;
   }
 
+  /**
+   * Display a new file change and update the tab title, caption, and icon.
+   */
   setChange(repoPath: string, change: IFileChange): void {
     this._change = change;
     this.content.setModel(fileChangeToDiffModel(repoPath, change));
@@ -104,21 +129,52 @@ export class DiffMainAreaWidget extends MainAreaWidget<XtralabDiffWidget> {
   private _pinnedChanged = new Signal<this, boolean>(this);
 }
 
+/**
+ * The options used to create a diff main area widget.
+ */
 interface ICreateDiffWidgetOptions {
+  /**
+   * The server-relative path of the repository containing the change.
+   */
   repoPath: string;
+  /**
+   * The file change to display.
+   */
   change: IFileChange;
+  /**
+   * Theme manager the diff view follows; may be `null`.
+   */
   themeManager: IThemeManager | null;
+  /**
+   * Contents manager used to write hunk-discard results.
+   */
   contentsManager: Contents.IManager;
+  /**
+   * Rendermime registry used by notebook diffs; may be `null`.
+   */
   rendermime: IRenderMimeRegistry | null;
+  /**
+   * Ask-agent popup for prompting an agent about diff lines; may be `null`.
+   */
   askAgent: IAskAgent | null;
+  /**
+   * The display choices shared by all diff views.
+   */
+  preferences: IDiffPreferences;
+  /**
+   * Translation bundle for user-facing strings.
+   */
   trans: TranslationBundle;
+  /**
+   * Whether the widget opens pinned instead of as the shared preview.
+   */
   pinned?: boolean;
+  /**
+   * Callback invoked when the widget becomes pinned.
+   */
   onPinned?: (widget: DiffMainAreaWidget) => void;
 }
 
-/**
- * Build the launcher's diff tab around the shared diff widget.
- */
 function createDiffWidget(
   options: ICreateDiffWidgetOptions
 ): DiffMainAreaWidget {
@@ -129,12 +185,13 @@ function createDiffWidget(
     contentsManager,
     rendermime,
     askAgent,
+    preferences,
     trans
   } = options;
   const pinned = options.pinned === true;
   const content = new XtralabDiffWidget(
     fileChangeToDiffModel(repoPath, change),
-    { contentsManager, rendermime, themeManager, askAgent, trans }
+    { contentsManager, rendermime, themeManager, askAgent, preferences, trans }
   );
   const widget = new DiffMainAreaWidget({ content }, change, pinned, trans);
   widget.id = pinned ? pinnedDiffWidgetId(change) : PREVIEW_DIFF_WIDGET_ID;
@@ -158,7 +215,6 @@ function createDiffWidget(
   widget.toolbar.addItem('pin', pinButton);
   addDiffToolbarItems(widget.toolbar, content);
 
-  // Keep chrome visible only while there is a relevant toolbar control.
   const syncToolbarVisibility = (): void => {
     if (widget.isDisposed) {
       return;
@@ -186,7 +242,6 @@ function createDiffWidget(
     }
     syncToolbarVisibility();
   };
-  // Auto-close once a discard leaves nothing to show.
   const onEmptied = (): void => {
     if (!widget.isDisposed) {
       widget.close();
@@ -206,8 +261,17 @@ function createDiffWidget(
   return widget;
 }
 
+/**
+ * The options for {@link registerGitCommands}.
+ */
 interface IRegisterGitCommandsOptions {
+  /**
+   * The JupyterLab application, providing the commands registry and shell.
+   */
   app: JupyterFrontEnd;
+  /**
+   * Theme manager the diff views follow; may be `null`.
+   */
   themeManager: IThemeManager | null;
   /**
    * Contents manager used to write hunk-discard results.
@@ -221,6 +285,10 @@ interface IRegisterGitCommandsOptions {
    * Ask-agent popup for prompting an agent about diff lines; may be `null`.
    */
   askAgent: IAskAgent | null;
+  /**
+   * The display choices shared by all diff views.
+   */
+  preferences: IDiffPreferences;
   /**
    * Translation bundle for user-facing strings.
    */
@@ -233,12 +301,14 @@ interface IRegisterGitCommandsOptions {
    * Look up an already-open diff widget for a file change.
    */
   findDiff(change: IFileChange, pin?: boolean): DiffMainAreaWidget | undefined;
+  /**
+   * Callback invoked when a preview diff widget becomes pinned.
+   */
   onPinned(widget: DiffMainAreaWidget): void;
 }
 
 /**
- * Register the launcher's git diff command on the application command
- * registry.
+ * Register the launcher's git diff command.
  */
 export function registerGitCommands(
   options: IRegisterGitCommandsOptions
@@ -249,6 +319,7 @@ export function registerGitCommands(
     contentsManager,
     rendermime,
     askAgent,
+    preferences,
     trans,
     trackDiff,
     findDiff,
@@ -280,6 +351,7 @@ export function registerGitCommands(
         contentsManager,
         rendermime,
         askAgent,
+        preferences,
         trans,
         pinned: pin,
         onPinned

package/src/git/diffModel.ts

@@ -80,14 +80,39 @@ class FileChangeDiffModel implements IXtralabDiffModel {
     };
   }
 
+  /**
+   * A signal emitted when the reference or challenger changes; this static
+   * model never emits it.
+   */
   readonly changed: ISignal<Git.Diff.IModel, Git.Diff.IModelChange> =
     new Signal<Git.Diff.IModel, Git.Diff.IModelChange>(this);
+  /**
+   * The reference (old) side of the diff.
+   */
   reference: Git.Diff.IContent;
+  /**
+   * The challenger (new) side of the diff.
+   */
   challenger: Git.Diff.IContent;
+  /**
+   * Repo-relative path of the changed file.
+   */
   readonly filename: string;
+  /**
+   * The rename source path; `undefined` for non-renames.
+   */
   readonly oldFilename: string | undefined;
+  /**
+   * Path of the git repository, relative to the server root.
+   */
   readonly repositoryPath: string;
+  /**
+   * Whether the file content is binary.
+   */
   readonly isBinary: boolean;
+  /**
+   * Whether hunks can be discarded through a working-tree save.
+   */
   readonly canDiscard: boolean;
 }
 

package/src/git/diffPreferences.ts

@@ -0,0 +1,192 @@
+import * as React from 'react';
+
+import type { ISettingRegistry } from '@jupyterlab/settingregistry';
+import type { IStateDB } from '@jupyterlab/statedb';
+import { Token } from '@lumino/coreutils';
+import { ISignal, Signal } from '@lumino/signaling';
+
+export type DiffStyle = 'split' | 'unified';
+
+export type DiffStyleControlMode = 'buttons' | 'toggle';
+
+export type NotebookDiffViewMode = 'notebook' | 'json';
+
+export type ImageDiffViewMode = '2-up' | 'swipe' | 'onion';
+
+export const MIN_SPLIT_RATIO = 0.1;
+export const MAX_SPLIT_RATIO = 0.9;
+export const DEFAULT_SPLIT_RATIO = 0.5;
+
+const SPLIT_RATIO_STATE_KEY = 'xtralab:git-diff:split-ratio';
+
+/**
+ * Display choices shared by every diff view. The toggles live in the
+ * plugin settings; the split width lives in the state database.
+ */
+export interface IDiffPreferences {
+  /**
+   * The current values; a new object after each change.
+   */
+  readonly values: IDiffPreferences.IValues;
+  /**
+   * A signal emitted when any value changes.
+   */
+  readonly changed: ISignal<IDiffPreferences, void>;
+  /**
+   * Change some values and persist them.
+   */
+  update(values: Partial<IDiffPreferences.IValues>): void;
+}
+
+export namespace IDiffPreferences {
+  /**
+   * The diff display values.
+   */
+  export interface IValues {
+    /**
+     * Split or unified layout for textual file diffs.
+     */
+    diffStyle: DiffStyle;
+    /**
+     * Two toolbar buttons for the layout, or one button that toggles it.
+     */
+    diffStyleControl: DiffStyleControlMode;
+    /**
+     * Whether long lines wrap instead of scrolling horizontally.
+     */
+    lineWrap: boolean;
+    /**
+     * Rendered or JSON view for notebook diffs.
+     */
+    notebookViewMode: NotebookDiffViewMode;
+    /**
+     * Comparison mode for image diffs.
+     */
+    imageViewMode: ImageDiffViewMode;
+    /**
+     * Width of the left pane in split view, as a fraction of the diff width.
+     */
+    splitRatio: number;
+  }
+}
+
+export const IDiffPreferences = new Token<IDiffPreferences>(
+  'xtralab:IDiffPreferences',
+  'Display choices shared by the git diff views.'
+);
+
+type SettingKey = Exclude<keyof IDiffPreferences.IValues, 'splitRatio'>;
+
+const SETTING_KEYS: SettingKey[] = [
+  'diffStyle',
+  'diffStyleControl',
+  'lineWrap',
+  'notebookViewMode',
+  'imageViewMode'
+];
+
+/**
+ * {@link IDiffPreferences} backed by the settings registry and the state
+ * database. Without them it keeps the values in memory only.
+ */
+export class DiffPreferences implements IDiffPreferences {
+  get values(): IDiffPreferences.IValues {
+    return this._values;
+  }
+
+  get changed(): ISignal<this, void> {
+    return this._changed;
+  }
+
+  update(values: Partial<IDiffPreferences.IValues>): void {
+    if (!this._apply(values)) {
+      return;
+    }
+    for (const key of SETTING_KEYS) {
+      if (key in values) {
+        this._settings?.set(key, this._values[key]).catch(reason => {
+          console.error(`xtralab: failed to save the diff ${key}`, reason);
+        });
+      }
+    }
+    if ('splitRatio' in values) {
+      this._state
+        ?.save(SPLIT_RATIO_STATE_KEY, this._values.splitRatio)
+        .catch(reason => {
+          console.error('xtralab: failed to save the diff split', reason);
+        });
+    }
+  }
+
+  /**
+   * Read the toggles from the plugin settings and follow their changes.
+   */
+  connectSettings(settings: ISettingRegistry.ISettings): void {
+    this._settings = settings;
+    const sync = (): void => {
+      this._apply(settings.composite as Partial<IDiffPreferences.IValues>);
+    };
+    sync();
+    settings.changed.connect(sync);
+  }
+
+  /**
+   * Restore the split width from the state database and save it there.
+   */
+  async connectState(state: IStateDB): Promise<void> {
+    this._state = state;
+    const ratio = await state.fetch(SPLIT_RATIO_STATE_KEY);
+    if (
+      typeof ratio === 'number' &&
+      ratio >= MIN_SPLIT_RATIO &&
+      ratio <= MAX_SPLIT_RATIO
+    ) {
+      this._apply({ splitRatio: ratio });
+    }
+  }
+
+  /**
+   * Merge values without persisting them; return whether one changed.
+   */
+  private _apply(values: Partial<IDiffPreferences.IValues>): boolean {
+    const next = { ...this._values, ...values };
+    const keys = Object.keys(next) as (keyof IDiffPreferences.IValues)[];
+    if (keys.every(key => next[key] === this._values[key])) {
+      return false;
+    }
+    this._values = next;
+    this._changed.emit();
+    return true;
+  }
+
+  private _values: IDiffPreferences.IValues = {
+    diffStyle: 'split',
+    diffStyleControl: 'buttons',
+    lineWrap: false,
+    notebookViewMode: 'notebook',
+    imageViewMode: '2-up',
+    splitRatio: DEFAULT_SPLIT_RATIO
+  };
+  private _changed = new Signal<this, void>(this);
+  private _settings: ISettingRegistry.ISettings | null = null;
+  private _state: IStateDB | null = null;
+}
+
+/**
+ * Re-render on every preference change and return the current values.
+ */
+export function useDiffPreferences(
+  preferences: IDiffPreferences
+): IDiffPreferences.IValues {
+  const subscribe = React.useCallback(
+    (onChange: () => void) => {
+      const slot = (): void => onChange();
+      preferences.changed.connect(slot);
+      return () => {
+        preferences.changed.disconnect(slot);
+      };
+    },
+    [preferences]
+  );
+  return React.useSyncExternalStore(subscribe, () => preferences.values);
+}

package/src/git/diffProvider.tsx

@@ -9,6 +9,7 @@ import { Git, IGitExtension } from '@jupyterlab/git';
 
 import { IAskAgent } from '../askAgent/tokens';
 
+import { DiffPreferences, IDiffPreferences } from './diffPreferences';
 import {
   IXtralabDiffContext,
   XtralabDiffWidget,
@@ -37,14 +38,21 @@ 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, ITranslator, IAskAgent],
+  optional: [
+    IRenderMimeRegistry,
+    IThemeManager,
+    ITranslator,
+    IAskAgent,
+    IDiffPreferences
+  ],
   activate: (
     app: JupyterFrontEnd,
     gitExtension: IGitExtension,
     rendermime: IRenderMimeRegistry | null,
     themeManager: IThemeManager | null,
     translator: ITranslator | null,
-    askAgent: IAskAgent | null
+    askAgent: IAskAgent | null,
+    preferences: IDiffPreferences | null
   ): void => {
     const trans = (translator ?? nullTranslator).load('jupyterlab');
     const factory = makeXtralabDiffFactory({
@@ -52,6 +60,7 @@ const diffProviderPlugin: JupyterFrontEndPlugin<void> = {
       rendermime,
       themeManager,
       askAgent,
+      preferences: preferences ?? new DiffPreferences(),
       trans
     });