xtralab 0.4.0 → 0.6.0

package/lib/git/diffProvider.js

@@ -0,0 +1,314 @@
+import * as React from 'react';
+import { IThemeManager } from '@jupyterlab/apputils';
+import { PathExt } from '@jupyterlab/coreutils';
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import { ReactWidget } from '@jupyterlab/ui-components';
+import { Git, IGitExtension } from '@jupyterlab/git';
+import { PromiseDelegate } from '@lumino/coreutils';
+import { Signal } from '@lumino/signaling';
+import { DIFF_WIDGET_CSS_CLASS, DiffSurface, NotebookViewModeControl, isDarkTheme, readStoredNotebookViewMode, writeStoredNotebookViewMode } from './diffSurface';
+import { IMAGE_DIFF_EXTENSIONS, imageDataType } from './imageDiff';
+/**
+ * A `Git.Diff.IDiffWidget` that renders through {@link DiffSurface}.
+ *
+ * `jupyterlab-git` constructs this via the registered factory, hosts it in
+ * its own `PreviewMainAreaWidget`, and reads `model` / calls `refresh()` /
+ * `getResolvedFile()` on it. It owns the notebook view-mode state (mounted
+ * into the diff toolbar `jupyterlab-git` hands the factory) and a reload
+ * nonce so `refresh()` re-pulls the model's content.
+ */
+class XtralabDiffWidget extends ReactWidget {
+    constructor(model, context) {
+        super();
+        this._reloadNonce = 0;
+        this._pendingRefresh = null;
+        this._notebookViewModeChanged = new Signal(this);
+        this._hasNotebookView = false;
+        this._hasNotebookViewChanged = new Signal(this);
+        this._model = model;
+        this._context = context;
+        this._notebookViewMode = readStoredNotebookViewMode();
+        // `jp-git-diff-root` borrows jupyterlab-git's host sizing (height:100%
+        // flex column inside its PreviewMainAreaWidget); `jp-xtralab-DiffWidget`
+        // brings our diff theming + the `.jp-xtralab-DiffWidget-*` styles.
+        this.addClass('jp-git-diff-root');
+        this.addClass(DIFF_WIDGET_CSS_CLASS);
+    }
+    /** The diff model, as required by `Git.Diff.IDiffWidget`. */
+    get model() {
+        return this._model;
+    }
+    /**
+     * We render a two-way (reference vs. challenger) view and do not provide
+     * a merge editor, so there is nothing to leave unresolved — report
+     * resolved so jupyterlab-git's merge-conflict flow is not blocked.
+     */
+    get isFileResolved() {
+        return true;
+    }
+    /**
+     * Used by jupyterlab-git's "Mark as resolved" button. For merge
+     * conflicts, jupyterlab-git passes the working-tree result as `base`;
+     * keep that content rather than overwriting it with either compared side.
+     */
+    async getResolvedFile() {
+        const source = this._model.hasConflict === true && this._model.base !== undefined
+            ? this._model.base
+            : this._model.challenger;
+        const content = await source.content();
+        return {
+            type: 'file',
+            format: imageDataType(this._model.filename) !== null ? 'base64' : 'text',
+            content
+        };
+    }
+    /**
+     * Re-pull both sides of the model and re-render. jupyterlab-git wires a
+     * "Refresh" toolbar button to this whenever `model.changed` fires (e.g.
+     * the compared `HEAD` moved).
+     */
+    async refresh() {
+        const done = new PromiseDelegate();
+        this._pendingRefresh = done;
+        this._reloadNonce += 1;
+        this.update();
+        await done.promise;
+    }
+    /** The notebook rendered-vs-JSON choice; mirrored into the toolbar. */
+    get notebookViewMode() {
+        return this._notebookViewMode;
+    }
+    setNotebookViewMode(mode) {
+        if (mode === this._notebookViewMode) {
+            return;
+        }
+        this._notebookViewMode = mode;
+        writeStoredNotebookViewMode(mode);
+        this._notebookViewModeChanged.emit(mode);
+    }
+    get notebookViewModeChanged() {
+        return this._notebookViewModeChanged;
+    }
+    get hasNotebookView() {
+        return this._hasNotebookView;
+    }
+    setHasNotebookView(value) {
+        if (value === this._hasNotebookView) {
+            return;
+        }
+        this._hasNotebookView = value;
+        this._hasNotebookViewChanged.emit(value);
+    }
+    get hasNotebookViewChanged() {
+        return this._hasNotebookViewChanged;
+    }
+    /** Resolve the in-flight {@link refresh} promise, if any. */
+    settleRefresh() {
+        const pending = this._pendingRefresh;
+        this._pendingRefresh = null;
+        pending === null || pending === void 0 ? void 0 : pending.resolve();
+    }
+    get reloadNonce() {
+        return this._reloadNonce;
+    }
+    get context() {
+        return this._context;
+    }
+    render() {
+        return React.createElement(ModelDiffView, { widget: this });
+    }
+}
+function ModelDiffView(props) {
+    const { widget } = props;
+    const model = widget.model;
+    const { contentsManager, rendermime, themeManager } = widget.context;
+    const nonce = widget.reloadNonce;
+    const [state, setState] = React.useState({
+        loading: true,
+        oldText: '',
+        newText: '',
+        error: null
+    });
+    // Mirror the widget's notebook view mode so toolbar-driven changes
+    // re-render the diff. The widget owns the canonical value (so the
+    // toolbar can read/write it without going through React).
+    const [notebookViewMode, setNotebookViewMode] = React.useState(() => widget.notebookViewMode);
+    React.useEffect(() => {
+        const handler = (_sender, mode) => {
+            setNotebookViewMode(mode);
+        };
+        widget.notebookViewModeChanged.connect(handler);
+        setNotebookViewMode(widget.notebookViewMode);
+        return () => {
+            widget.notebookViewModeChanged.disconnect(handler);
+        };
+    }, [widget]);
+    const handleNotebookAvailabilityChange = React.useCallback((available) => {
+        widget.setHasNotebookView(available);
+    }, [widget]);
+    const [dark, setDark] = React.useState(() => isDarkTheme(themeManager));
+    React.useEffect(() => {
+        if (themeManager !== null) {
+            const handler = () => setDark(isDarkTheme(themeManager));
+            themeManager.themeChanged.connect(handler);
+            return () => {
+                themeManager.themeChanged.disconnect(handler);
+            };
+        }
+        const observer = new MutationObserver(() => setDark(isDarkTheme(themeManager)));
+        observer.observe(document.body, {
+            attributes: true,
+            attributeFilter: ['data-jp-theme-light']
+        });
+        return () => {
+            observer.disconnect();
+        };
+    }, [themeManager]);
+    // Fetch both sides whenever the model or the reload nonce changes. The
+    // model's `content()` getters target the right git refs internally
+    // (working tree, index, a commit, …) so we stay content-source-agnostic.
+    React.useEffect(() => {
+        let cancelled = false;
+        setState({ loading: true, oldText: '', newText: '', error: null });
+        void (async () => {
+            try {
+                const [oldText, newText] = await Promise.all([
+                    model.reference.content(),
+                    model.challenger.content()
+                ]);
+                if (cancelled) {
+                    return;
+                }
+                setState({
+                    loading: false,
+                    oldText: oldText !== null && oldText !== void 0 ? oldText : '',
+                    newText: newText !== null && newText !== void 0 ? newText : '',
+                    error: null
+                });
+            }
+            catch (err) {
+                if (cancelled) {
+                    return;
+                }
+                setState({
+                    loading: false,
+                    oldText: '',
+                    newText: '',
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            }
+            finally {
+                if (!cancelled) {
+                    // Let an in-flight `widget.refresh()` resolve once the reload
+                    // has settled (jupyterlab-git only awaits it to hide its
+                    // refresh button).
+                    widget.settleRefresh();
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [widget, model, nonce]);
+    // Per-hunk discard is only meaningful when the challenger is the working
+    // tree (an unstaged change) and we are not in a three-way merge view.
+    const canDiscardHunk = model.challenger.source === Git.Diff.SpecialRef.WORKING &&
+        model.hasConflict !== true;
+    const serverPath = React.useMemo(() => { var _a; return PathExt.join((_a = model.repositoryPath) !== null && _a !== void 0 ? _a : '', model.filename); }, [model.repositoryPath, model.filename]);
+    const hunkDiscard = React.useMemo(() => ({
+        enabled: canDiscardHunk,
+        save: async (text) => {
+            await contentsManager.save(serverPath, {
+                type: 'file',
+                format: 'text',
+                content: text
+            });
+        },
+        onAfterSave: () => {
+            // jupyterlab-git's panel auto-refreshes off the contents
+            // `fileChanged` signal the save above emits; we just need to
+            // re-pull so the diff reflects the reverted hunk. (We do not
+            // auto-close: jupyterlab-git owns the diff tab.)
+            void widget.refresh();
+        }
+    }), [canDiscardHunk, contentsManager, serverPath, widget]);
+    return (React.createElement(DiffSurface, { loading: state.loading, error: state.error, isBinary: false, oldText: state.oldText, newText: state.newText, newName: model.filename, oldName: model.filename, dark: dark, rendermime: rendermime, notebookViewMode: notebookViewMode, onNotebookAvailabilityChange: handleNotebookAvailabilityChange, hunkDiscard: hunkDiscard }));
+}
+/**
+ * Notebook/JSON toggle mounted into the diff toolbar that jupyterlab-git
+ * passes to the factory. Bound to the widget's signals so it stays in sync
+ * with the rendered surface and only appears for parseable notebooks.
+ */
+class NotebookViewModeToolbarItem extends ReactWidget {
+    constructor(widget) {
+        super();
+        this._widget = widget;
+        this.addClass('jp-xtralab-DiffWidget-viewModeToolbarItem');
+    }
+    render() {
+        return React.createElement(ToolbarControl, { widget: this._widget });
+    }
+}
+function ToolbarControl(props) {
+    const { widget } = props;
+    const [mode, setMode] = React.useState(() => widget.notebookViewMode);
+    const [available, setAvailable] = React.useState(() => widget.hasNotebookView);
+    React.useEffect(() => {
+        const onMode = (_sender, next) => {
+            setMode(next);
+        };
+        const onAvailable = (_sender, next) => {
+            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]);
+    return (React.createElement(NotebookViewModeControl, { mode: mode, available: available, onChange: next => widget.setNotebookViewMode(next) }));
+}
+/**
+ * Build the `Git.Diff.Factory` xtralab registers with jupyterlab-git. The
+ * factory closes over the application-level context (contents manager for
+ * hunk discard, rendermime for notebook outputs, theme manager) that the
+ * `Git.Diff.IFactoryOptions` does not carry.
+ */
+function makeXtralabDiffFactory(context) {
+    return async (options) => {
+        const widget = new XtralabDiffWidget(options.model, context);
+        if (options.toolbar) {
+            options.toolbar.addItem('xtralab-notebook-view-mode', new NotebookViewModeToolbarItem(widget));
+        }
+        return widget;
+    };
+}
+/**
+ * Registers xtralab's diff rendering as jupyterlab-git's diff providers:
+ * `@pierre/diffs` for text and notebooks, the bundled `<img>`-based view
+ * for raster images.
+ */
+const diffProviderPlugin = {
+    id: 'xtralab:git-diff-providers',
+    description: "Replaces jupyterlab-git's notebook, text and image diff plugins with xtralab's renderer.",
+    autoStart: true,
+    requires: [IGitExtension],
+    optional: [IRenderMimeRegistry, IThemeManager],
+    activate: (app, gitExtension, rendermime, themeManager) => {
+        const factory = makeXtralabDiffFactory({
+            contentsManager: app.serviceManager.contents,
+            rendermime,
+            themeManager
+        });
+        // Notebooks and raster images get extension-specific providers; every
+        // other text file falls back to the same factory. One factory serves
+        // all three — the surface auto-detects notebooks/images by filename.
+        gitExtension.registerDiffProvider('XtralabNotebook', ['.ipynb'], factory);
+        gitExtension.registerDiffProvider('XtralabImage', IMAGE_DIFF_EXTENSIONS, factory);
+        gitExtension.registerFallbackDiffProvider(factory);
+    }
+};
+export default diffProviderPlugin;

package/lib/git/diffSurface.d.ts

@@ -0,0 +1,115 @@
+import * as React from 'react';
+import { IThemeManager } from '@jupyterlab/apputils';
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+/**
+ * Shared diff rendering surface used by both diff hosts in this extension:
+ *
+ *   - the launcher dashboard's own `xtralab:git:open-diff` command
+ *     (via {@link DiffContentWidget} in `diffWidget.tsx`), and
+ *   - the `jupyterlab-git` diff providers registered into the upstream git
+ *     panel (via `XtralabDiffWidget` in `diffProvider.tsx`).
+ *
+ * The surface is deliberately content-source agnostic: callers resolve the
+ * old/new text however they like (xtralab's REST helper, or a
+ * `Git.Diff.IModel`'s `content()` getters) and hand the resolved strings in.
+ * Everything visual — the `@pierre/diffs` split view, the cell-by-cell
+ * notebook view, the draggable column resizer, and the per-hunk discard
+ * affordance — lives here so the two hosts stay pixel-identical.
+ */
+/**
+ * The CSS class added to the diff main-area widget. The selectors that
+ * style the embedded `@pierre/diffs` viewer hang off this class.
+ */
+export declare const DIFF_WIDGET_CSS_CLASS = "jp-xtralab-DiffWidget";
+/**
+ * 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, …).
+ */
+export declare function isDarkTheme(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}.
+ */
+export interface IHunkDiscard {
+    enabled: boolean;
+    save: (fullText: string) => Promise<void>;
+    onAfterSave: () => void;
+}
+export interface IDiffSurfaceProps {
+    /** Whether the host is still resolving the file contents. */
+    loading: boolean;
+    /** Fatal error message to show instead of a diff, or `null`. */
+    error: string | null;
+    /** Whether the file is binary (no textual diff is rendered). */
+    isBinary: boolean;
+    /** Resolved old/reference text. Ignored while loading/binary/errored. */
+    oldText: string;
+    /** Resolved new/challenger text. Ignored while loading/binary/errored. */
+    newText: string;
+    /**
+     * New-side path. Drives notebook detection and the `@pierre/diffs` file
+     * name on the additions side.
+     */
+    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.
+     */
+    oldName?: string;
+    /** Whether to render with the dark `@pierre/diffs` theme. */
+    dark: 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.
+     */
+    rendermime: IRenderMimeRegistry | null;
+    /** Current rendered-vs-JSON choice for notebook diffs (host-controlled). */
+    notebookViewMode: NotebookDiffViewMode;
+    /**
+     * Called whenever the availability of a rendered notebook view changes,
+     * so the host can show/hide its Notebook/JSON toolbar toggle.
+     */
+    onNotebookAvailabilityChange?: (available: 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.
+     */
+    onMetadataChange?: (info: {
+        hunkCount: number | null;
+    }) => void;
+    /** Optional per-hunk discard wiring; omit for a read-only diff. */
+    hunkDiscard?: IHunkDiscard;
+}
+/**
+ * The shared, content-source-agnostic diff renderer. See the module
+ * docstring for the division of labor between this surface and its hosts.
+ */
+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}.
+ */
+export declare function NotebookViewModeControl(props: {
+    mode: NotebookDiffViewMode;
+    available: boolean;
+    onChange: (mode: NotebookDiffViewMode) => void;
+}): React.ReactElement;