xtralab 0.15.0 → 0.15.2

package/lib/git/diffModel.js

@@ -40,6 +40,10 @@ function referenceSource(ref) {
 class FileChangeDiffModel {
     constructor(repoPath, change) {
         var _a;
+        /**
+         * A signal emitted when the reference or challenger changes; this static
+         * model never emits it.
+         */
         this.changed = new Signal(this);
         const { oldRef, newRef } = resolveReferences(change);
         // Renames compare the new path against the old path's previous content.

package/lib/git/diffPreferences.d.ts

@@ -0,0 +1,90 @@
+import type { ISettingRegistry } from '@jupyterlab/settingregistry';
+import type { IStateDB } from '@jupyterlab/statedb';
+import { Token } from '@lumino/coreutils';
+import { ISignal } 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 declare const MIN_SPLIT_RATIO = 0.1;
+export declare const MAX_SPLIT_RATIO = 0.9;
+export declare const DEFAULT_SPLIT_RATIO = 0.5;
+/**
+ * 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 declare namespace IDiffPreferences {
+    /**
+     * The diff display values.
+     */
+    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 declare const IDiffPreferences: Token<IDiffPreferences>;
+/**
+ * {@link IDiffPreferences} backed by the settings registry and the state
+ * database. Without them it keeps the values in memory only.
+ */
+export declare class DiffPreferences implements IDiffPreferences {
+    get values(): IDiffPreferences.IValues;
+    get changed(): ISignal<this, void>;
+    update(values: Partial<IDiffPreferences.IValues>): void;
+    /**
+     * Read the toggles from the plugin settings and follow their changes.
+     */
+    connectSettings(settings: ISettingRegistry.ISettings): void;
+    /**
+     * Restore the split width from the state database and save it there.
+     */
+    connectState(state: IStateDB): Promise<void>;
+    /**
+     * Merge values without persisting them; return whether one changed.
+     */
+    private _apply;
+    private _values;
+    private _changed;
+    private _settings;
+    private _state;
+}
+/**
+ * Re-render on every preference change and return the current values.
+ */
+export declare function useDiffPreferences(preferences: IDiffPreferences): IDiffPreferences.IValues;

package/lib/git/diffPreferences.js

@@ -0,0 +1,107 @@
+import * as React from 'react';
+import { Token } from '@lumino/coreutils';
+import { Signal } from '@lumino/signaling';
+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';
+export const IDiffPreferences = new Token('xtralab:IDiffPreferences', 'Display choices shared by the git diff views.');
+const SETTING_KEYS = [
+    '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 {
+    constructor() {
+        this._values = {
+            diffStyle: 'split',
+            diffStyleControl: 'buttons',
+            lineWrap: false,
+            notebookViewMode: 'notebook',
+            imageViewMode: '2-up',
+            splitRatio: DEFAULT_SPLIT_RATIO
+        };
+        this._changed = new Signal(this);
+        this._settings = null;
+        this._state = null;
+    }
+    get values() {
+        return this._values;
+    }
+    get changed() {
+        return this._changed;
+    }
+    update(values) {
+        var _a, _b;
+        if (!this._apply(values)) {
+            return;
+        }
+        for (const key of SETTING_KEYS) {
+            if (key in values) {
+                (_a = this._settings) === null || _a === void 0 ? void 0 : _a.set(key, this._values[key]).catch(reason => {
+                    console.error(`xtralab: failed to save the diff ${key}`, reason);
+                });
+            }
+        }
+        if ('splitRatio' in values) {
+            (_b = this._state) === null || _b === void 0 ? void 0 : _b.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) {
+        this._settings = settings;
+        const sync = () => {
+            this._apply(settings.composite);
+        };
+        sync();
+        settings.changed.connect(sync);
+    }
+    /**
+     * Restore the split width from the state database and save it there.
+     */
+    async connectState(state) {
+        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.
+     */
+    _apply(values) {
+        const next = { ...this._values, ...values };
+        const keys = Object.keys(next);
+        if (keys.every(key => next[key] === this._values[key])) {
+            return false;
+        }
+        this._values = next;
+        this._changed.emit();
+        return true;
+    }
+}
+/**
+ * Re-render on every preference change and return the current values.
+ */
+export function useDiffPreferences(preferences) {
+    const subscribe = React.useCallback((onChange) => {
+        const slot = () => onChange();
+        preferences.changed.connect(slot);
+        return () => {
+            preferences.changed.disconnect(slot);
+        };
+    }, [preferences]);
+    return React.useSyncExternalStore(subscribe, () => preferences.values);
+}

package/lib/git/diffProvider.js

@@ -3,6 +3,7 @@ import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 import { IGitExtension } from '@jupyterlab/git';
 import { IAskAgent } from '../askAgent/tokens';
+import { DiffPreferences, IDiffPreferences } from './diffPreferences';
 import { XtralabDiffWidget, addDiffToolbarItems } from './diffWidget';
 import { IMAGE_DIFF_EXTENSIONS } from './imageDiff';
 /**
@@ -22,14 +23,21 @@ const diffProviderPlugin = {
     description: "Replaces jupyterlab-git's notebook, text and image diff plugins with xtralab's renderer.",
     autoStart: true,
     requires: [IGitExtension],
-    optional: [IRenderMimeRegistry, IThemeManager, ITranslator, IAskAgent],
-    activate: (app, gitExtension, rendermime, themeManager, translator, askAgent) => {
+    optional: [
+        IRenderMimeRegistry,
+        IThemeManager,
+        ITranslator,
+        IAskAgent,
+        IDiffPreferences
+    ],
+    activate: (app, gitExtension, rendermime, themeManager, translator, askAgent, preferences) => {
         const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
         const factory = makeXtralabDiffFactory({
             contentsManager: app.serviceManager.contents,
             rendermime,
             themeManager,
             askAgent,
+            preferences: preferences !== null && preferences !== void 0 ? preferences : new DiffPreferences(),
             trans
         });
         // Use one shared factory; the surface detects notebooks/images by filename.

package/lib/git/diffSurface.d.ts

@@ -3,33 +3,11 @@ import { IThemeManager } from '@jupyterlab/apputils';
 import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import type { TranslationBundle } from '@jupyterlab/translation';
 import { type SelectedLineRange } from '@pierre/diffs';
-/**
- * The CSS class added to the diff main-area widget. The selectors that
- * style the embedded `@pierre/diffs` viewer hang off this class.
- */
+import { type DiffStyle, type DiffStyleControlMode, type ImageDiffViewMode, type NotebookDiffViewMode } from './diffPreferences';
 export declare const DIFF_WIDGET_CSS_CLASS = "jp-xtralab-DiffWidget";
 /**
- * Layout for textual/code diffs, forwarded to `@pierre/diffs` as its
- * `diffStyle` option. `split` is the side-by-side old|new view; `unified`
- * is the single-column inline view (what diffs.com calls "stacked").
- */
-export type DiffStyle = 'split' | 'unified';
-export declare function readStoredDiffStyle(): DiffStyle;
-export declare function writeStoredDiffStyle(style: DiffStyle): void;
-/**
- * View modes available for `.ipynb` diffs. `notebook` is the cell-by-cell
- * rendered view; `json` is the raw nbformat JSON file diff, for inspecting
- * exactly which bytes changed.
- */
-export type NotebookDiffViewMode = 'notebook' | 'json';
-export declare function readStoredNotebookViewMode(): NotebookDiffViewMode;
-export declare function writeStoredNotebookViewMode(mode: NotebookDiffViewMode): void;
-/**
- * Decide whether the active JupyterLab theme is a dark theme. Prefers the
- * `IThemeManager` token when available, and falls back to sniffing the
- * `data-jp-theme-light` attribute that JupyterLab sets on `<body>` so the
- * component still works in stripped-down hosts where the token isn't
- * provided (lite, certain notebook configurations, …).
+ * Dark-theme check via `IThemeManager`, falling back to the
+ * `data-jp-theme-light` body attribute for hosts without the token.
  */
 export declare function isDarkTheme(themeManager: IThemeManager | null): boolean;
 /**
@@ -37,18 +15,26 @@ export declare function isDarkTheme(themeManager: IThemeManager | null): boolean
  */
 export declare function isPierreTheme(themeManager: IThemeManager | null): boolean;
 /**
- * Optional per-hunk discard wiring. When supplied and `enabled`, each hunk
- * in a plain-text/code diff gets an inline "discard" button; clicking it
- * reverts that hunk and hands the rebuilt full-file text back to the host
- * via {@link IHunkDiscard.save}. The host owns the actual write (it knows
- * the on-disk path) and triggers any follow-up refresh in
- * {@link IHunkDiscard.onAfterSave}.
+ * Per-hunk discard wiring: discarding rebuilds the full file text and the
+ * host owns the write via `save`, then refreshes in `onAfterSave`.
  */
 interface IHunkDiscard {
+    /**
+     * Whether hunk discarding is available.
+     */
     enabled: boolean;
+    /**
+     * Persist the full post-discard file text.
+     */
     save: (fullText: string) => Promise<void>;
+    /**
+     * Called after a successful save so the host can refresh the diff.
+     */
     onAfterSave: () => void;
 }
+/**
+ * The props for the {@link DiffSurface} component.
+ */
 interface IDiffSurfaceProps {
     /**
      * Whether the host is still resolving the file contents.
@@ -71,13 +57,11 @@ interface IDiffSurfaceProps {
      */
     newText: string;
     /**
-     * New-side path. Drives notebook detection and the `@pierre/diffs` file
-     * name on the additions side.
+     * New-side path; drives notebook detection and the highlighting filename.
      */
     newName: string;
     /**
-     * Old-side path. Differs from {@link newName} only for renames; defaults
-     * to {@link newName} when the host does not track a previous path.
+     * Old-side path; differs from {@link newName} only for renames.
      */
     oldName?: string;
     /**
@@ -89,35 +73,48 @@ interface IDiffSurfaceProps {
      */
     pierreTheme: boolean;
     /**
-     * Rendermime registry used by the notebook view to render outputs and
-     * markdown cells. May be `null` in stripped-down hosts; the notebook
-     * diff falls back to a textual representation in that case.
+     * Used by the notebook view; `null` in stripped-down hosts, which forces a textual fallback.
      */
     rendermime: IRenderMimeRegistry | null;
     /**
-     * Current rendered-vs-JSON choice for notebook diffs (host-controlled).
+     * Rendered-vs-JSON choice for notebook diffs (host-controlled).
      */
     notebookViewMode: NotebookDiffViewMode;
     /**
-     * Split vs unified layout for the textual/code file diff (host-controlled).
+     * Split vs unified layout for the textual file diff (host-controlled).
      */
     diffStyle: DiffStyle;
     /**
-     * Called whenever the availability of a rendered notebook view changes,
-     * so the host can show/hide its Notebook/JSON toolbar toggle.
+     * Whether long lines wrap instead of scrolling horizontally (host-controlled).
+     */
+    lineWrap: boolean;
+    /**
+     * Left pane width in split view, as a fraction of the diff width (host-controlled).
+     */
+    splitRatio: number;
+    /**
+     * Called when the user finishes resizing the split panes.
+     */
+    onSplitRatioChange: (ratio: number) => void;
+    /**
+     * 2-up, swipe or onion view for image diffs (host-controlled).
+     */
+    imageViewMode: ImageDiffViewMode;
+    /**
+     * Called when the user picks another image view mode.
+     */
+    onImageViewModeChange: (mode: ImageDiffViewMode) => void;
+    /**
+     * Fires when rendered-notebook availability changes so the host can toggle its Notebook/JSON control.
      */
     onNotebookAvailabilityChange?: (available: boolean) => void;
     /**
-     * Called whenever the textual/code file diff (the only view the split vs
-     * unified choice affects) becomes the active view, so the host can
-     * show/hide its Split/Unified toolbar toggle. False for image, binary,
-     * rendered-notebook, loading and error states.
+     * Fires when the textual file diff becomes (in)active — the only view the split/unified choice affects.
      */
     onFileDiffActiveChange?: (active: boolean) => void;
     /**
-     * Called after each (re)computation of the diff with the number of hunks
-     * (or `null` when no textual diff exists). Hosts use this to implement
-     * post-discard behaviors such as auto-closing an emptied diff.
+     * Fires after each diff computation with the hunk count (`null` when no
+     * textual diff); hosts use it to auto-close emptied diffs.
      */
     onMetadataChange?: (info: {
         hunkCount: number | null;
@@ -127,11 +124,8 @@ interface IDiffSurfaceProps {
      */
     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.
+     * Enables line selection and the gutter "+" button; called with the
+     * selected range and the button's viewport rect (`null` when unmeasurable).
      */
     onLineAsk?: (range: SelectedLineRange, anchor: DOMRect | null) => void;
     /**
@@ -144,10 +138,8 @@ interface IDiffSurfaceProps {
  */
 export declare function DiffSurface(props: IDiffSurfaceProps): React.ReactElement;
 /**
- * Segmented Notebook/JSON selector. Hosts mount this into whatever toolbar
- * they own (the launcher's `MainAreaWidget` toolbar, or the
- * `jupyterlab-git`-provided diff toolbar) and drive its value/visibility
- * from the same state they pass to {@link DiffSurface}.
+ * Segmented Notebook/JSON selector. Hosts mount it into their own toolbar
+ * and drive value/visibility from the state they pass to {@link DiffSurface}.
  */
 export declare function NotebookViewModeControl(props: {
     mode: NotebookDiffViewMode;
@@ -156,16 +148,25 @@ export declare function NotebookViewModeControl(props: {
     trans: TranslationBundle;
 }): React.ReactElement;
 /**
- * Segmented Split/Unified selector. Mirrors {@link NotebookViewModeControl}:
- * hosts mount it into their own toolbar and drive its value/visibility from
- * the same state they pass to {@link DiffSurface}. Only meaningful while the
- * textual/code file diff is the active view, so `available` mirrors the
- * surface's `onFileDiffActiveChange`.
+ * Split/Unified selector: two segmented buttons, or with `control: 'toggle'`
+ * one button that shows the layout it switches to.
+ * `available` mirrors the surface's `onFileDiffActiveChange`.
  */
 export declare function DiffStyleControl(props: {
     diffStyle: DiffStyle;
+    control: DiffStyleControlMode;
     available: boolean;
     onChange: (style: DiffStyle) => void;
     trans: TranslationBundle;
 }): React.ReactElement;
+/**
+ * Line-wrap toggle styled as a one-button segmented control.
+ * `available` mirrors the surface's `onFileDiffActiveChange`.
+ */
+export declare function LineWrapControl(props: {
+    lineWrap: boolean;
+    available: boolean;
+    onChange: (wrap: boolean) => void;
+    trans: TranslationBundle;
+}): React.ReactElement;
 export {};