xtralab 0.4.0 → 0.5.0

package/lib/git/diffSurface.js

@@ -0,0 +1,342 @@
+import * as React from 'react';
+import { undoIcon } from '@jupyterlab/ui-components';
+import { FileDiff } from '@pierre/diffs/react';
+import { diffAcceptRejectHunk, parseDiffFromFile } from '@pierre/diffs';
+import { ImageDiffView, imageDataType } from './imageDiff';
+import { buildNotebookDiff, NotebookDiffView } from './notebookDiff';
+/**
+ * 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 const DIFF_WIDGET_CSS_CLASS = 'jp-xtralab-DiffWidget';
+/**
+ * `localStorage` key for the user's last-chosen split ratio, persisted so
+ * the preference survives reloads (the library has no built-in way to
+ * remember it).
+ */
+const SPLIT_RATIO_STORAGE_KEY = 'xtralab:diff-split-ratio';
+/**
+ * Bounds on the left-pane fraction. Keeping a few percent on either side
+ * guarantees both panes remain visible — dragging to 0/100 would hide a
+ * column and is almost never what the user wants.
+ */
+const MIN_SPLIT_RATIO = 0.1;
+const MAX_SPLIT_RATIO = 0.9;
+const DEFAULT_SPLIT_RATIO = 0.5;
+/**
+ * CSS injected via the `@pierre/diffs` `unsafeCSS` option. The library
+ * places it inside the shadow root under `@layer unsafe`, which beats
+ * the library's own `@layer base` rule that hardcodes
+ * `grid-template-columns: 1fr 1fr` on the split-mode container.
+ *
+ * The override reads from `--xtralab-split-cols`, a custom property we set
+ * on the host element via the `style` prop. Custom properties inherit
+ * through the shadow DOM boundary, so adjusting it on the host instantly
+ * resizes the columns without re-rendering the diff.
+ */
+const SPLIT_RESIZE_CSS = `pre[data-diff-type="split"][data-overflow="scroll"] {
+  grid-template-columns: var(--xtralab-split-cols, 1fr 1fr);
+}`;
+function readStoredSplitRatio() {
+    try {
+        const raw = window.localStorage.getItem(SPLIT_RATIO_STORAGE_KEY);
+        if (raw === null) {
+            return DEFAULT_SPLIT_RATIO;
+        }
+        const parsed = Number.parseFloat(raw);
+        if (Number.isFinite(parsed) &&
+            parsed >= MIN_SPLIT_RATIO &&
+            parsed <= MAX_SPLIT_RATIO) {
+            return parsed;
+        }
+    }
+    catch (_a) {
+        // localStorage may throw in privacy mode or sandboxed contexts. Falling
+        // back to the default is fine — the user can resize again on this run.
+    }
+    return DEFAULT_SPLIT_RATIO;
+}
+function writeStoredSplitRatio(ratio) {
+    try {
+        window.localStorage.setItem(SPLIT_RATIO_STORAGE_KEY, ratio.toString());
+    }
+    catch (_a) {
+        // See readStoredSplitRatio — best-effort persistence.
+    }
+}
+const NOTEBOOK_DIFF_VIEW_MODE_STORAGE_KEY = 'xtralab:notebook-diff-view-mode';
+export function readStoredNotebookViewMode() {
+    try {
+        const raw = window.localStorage.getItem(NOTEBOOK_DIFF_VIEW_MODE_STORAGE_KEY);
+        if (raw === 'json' || raw === 'notebook') {
+            return raw;
+        }
+    }
+    catch (_a) {
+        // See readStoredSplitRatio — privacy-mode / sandboxed contexts can
+        // throw on access. The notebook view is the better default anyway.
+    }
+    return 'notebook';
+}
+export function writeStoredNotebookViewMode(mode) {
+    try {
+        window.localStorage.setItem(NOTEBOOK_DIFF_VIEW_MODE_STORAGE_KEY, mode);
+    }
+    catch (_a) {
+        // Best-effort.
+    }
+}
+/**
+ * Detect notebook files by extension. We only look at the suffix so the
+ * caller doesn't need to plumb a content-type field through; mistaking
+ * another `.ipynb`-named file for a notebook is harmless because
+ * {@link buildNotebookDiff} validates the JSON shape and we fall back to
+ * the file diff if parsing fails.
+ */
+function isNotebookPath(path) {
+    return path.toLowerCase().endsWith('.ipynb');
+}
+/**
+ * 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 function isDarkTheme(themeManager) {
+    if (themeManager !== null && themeManager.theme !== null) {
+        return !themeManager.isLight(themeManager.theme);
+    }
+    return document.body.dataset.jpThemeLight === 'false';
+}
+/**
+ * The shared, content-source-agnostic diff renderer. See the module
+ * docstring for the division of labor between this surface and its hosts.
+ */
+export function DiffSurface(props) {
+    const { loading, error, isBinary, oldText, newText, newName, oldName, dark, rendermime, notebookViewMode, onNotebookAvailabilityChange, onMetadataChange, hunkDiscard } = props;
+    const hasContent = !loading && error === null && !isBinary;
+    // Raster images take a dedicated `<img>`-based view instead of a
+    // text/notebook diff; the host passes the two sides as base64 strings in
+    // `oldText`/`newText` (the git server base64-encodes binary content).
+    const imageType = React.useMemo(() => imageDataType(newName), [newName]);
+    // Pre-compute the line-oriented diff metadata. Owning it here lets us
+    // pass it to {@link FileDiff} *and* thread the same instance through
+    // {@link diffAcceptRejectHunk} when the user discards a hunk — so hunk
+    // indexes line up between what the user clicked and what we mutate.
+    const metadata = React.useMemo(() => {
+        if (!hasContent || imageType !== null) {
+            return null;
+        }
+        const oldFile = {
+            name: oldName !== null && oldName !== void 0 ? oldName : newName,
+            contents: oldText
+        };
+        const newFile = { name: newName, contents: newText };
+        return parseDiffFromFile(oldFile, newFile);
+    }, [hasContent, imageType, oldText, newText, oldName, newName]);
+    // Cell-by-cell notebook diff for `.ipynb` files. When non-null the
+    // renderer uses a notebook-aware view instead of the line-oriented file
+    // diff — kept distinct from {@link metadata} so a notebook whose JSON we
+    // cannot parse can fall back to the file diff path.
+    const notebookDiff = React.useMemo(() => {
+        if (!hasContent || imageType !== null || !isNotebookPath(newName)) {
+            return null;
+        }
+        return buildNotebookDiff({ oldText, newText });
+    }, [hasContent, imageType, oldText, newText, newName]);
+    // Tell the host whether a rendered notebook view is currently available
+    // so it can show/hide its Notebook/JSON toggle.
+    React.useEffect(() => {
+        onNotebookAvailabilityChange === null || onNotebookAvailabilityChange === void 0 ? void 0 : onNotebookAvailabilityChange(notebookDiff !== null);
+    }, [onNotebookAvailabilityChange, notebookDiff]);
+    // Report the diff shape so hosts can react (e.g. auto-close on empty).
+    React.useEffect(() => {
+        onMetadataChange === null || onMetadataChange === void 0 ? void 0 : onMetadataChange({
+            hunkCount: metadata !== null ? metadata.hunks.length : null
+        });
+    }, [onMetadataChange, metadata]);
+    // Split ratio for the diff columns: fraction of width given to the
+    // deletions (left) pane. Persisted across sessions so the user only
+    // dials in their layout once.
+    const [leftRatio, setLeftRatio] = React.useState(() => readStoredSplitRatio());
+    const wrapperRef = React.useRef(null);
+    // The drag handler reads the live ratio from a ref so the listeners we
+    // attach on pointer-down don't capture a stale value across renders.
+    const leftRatioRef = React.useRef(leftRatio);
+    React.useEffect(() => {
+        leftRatioRef.current = leftRatio;
+    }, [leftRatio]);
+    const canDiscardHunk = (hunkDiscard === null || hunkDiscard === void 0 ? void 0 : hunkDiscard.enabled) === true;
+    const lineAnnotations = React.useMemo(() => {
+        if (!canDiscardHunk || metadata === null) {
+            return [];
+        }
+        return metadata.hunks.map((hunk, hunkIndex) => ({
+            side: 'additions',
+            // The first line of each hunk in the new file. We anchor the button
+            // there so it sits at the top of the hunk's body.
+            lineNumber: hunk.additionStart,
+            metadata: { hunkIndex }
+        }));
+    }, [canDiscardHunk, metadata]);
+    const handleDiscardHunk = React.useCallback(async (hunkIndex) => {
+        if (metadata === null || hunkDiscard === undefined) {
+            return;
+        }
+        const updated = diffAcceptRejectHunk(metadata, hunkIndex, 'reject');
+        // `additionLines` after a 'reject' contains the full new file with
+        // the hunk reverted back to the old content. The library splits
+        // file contents with `/(?<=\n)/` (a lookbehind that keeps the
+        // trailing `\n` on each line), so the entries already carry their
+        // own line endings — joining with `''` rebuilds the original text
+        // verbatim, while joining with `'\n'` would double every newline.
+        const text = updated.additionLines.join('');
+        try {
+            await hunkDiscard.save(text);
+            hunkDiscard.onAfterSave();
+        }
+        catch (err) {
+            console.error('xtralab: failed to discard hunk', err);
+        }
+    }, [hunkDiscard, metadata]);
+    const renderAnnotation = React.useCallback((annotation) => {
+        if (annotation.metadata === undefined) {
+            return null;
+        }
+        const { hunkIndex } = annotation.metadata;
+        return (React.createElement("div", { className: "jp-xtralab-DiffWidget-hunkAnnotation" },
+            React.createElement("button", { type: "button", className: "jp-xtralab-DiffWidget-hunkButton", title: "Discard this hunk's changes", "aria-label": "Discard hunk", onClick: () => void handleDiscardHunk(hunkIndex) },
+                React.createElement(undoIcon.react, { tag: "span", className: "jp-xtralab-DiffWidget-hunkButton-icon", elementSize: "normal" }))));
+    }, [handleDiscardHunk]);
+    const handleResizerPointerDown = React.useCallback((event) => {
+        // Only react to primary-button drags. Right-click / middle-click on
+        // the handle should pass through to the browser default.
+        if (event.button !== 0) {
+            return;
+        }
+        const wrapper = wrapperRef.current;
+        if (wrapper === null) {
+            return;
+        }
+        event.preventDefault();
+        const handle = event.currentTarget;
+        handle.setPointerCapture(event.pointerId);
+        handle.dataset.dragging = 'true';
+        const rect = wrapper.getBoundingClientRect();
+        const startX = event.clientX;
+        const startRatio = leftRatioRef.current;
+        const onPointerMove = (ev) => {
+            if (rect.width <= 0) {
+                return;
+            }
+            const next = startRatio + (ev.clientX - startX) / rect.width;
+            const clamped = Math.max(MIN_SPLIT_RATIO, Math.min(MAX_SPLIT_RATIO, next));
+            setLeftRatio(clamped);
+        };
+        const onPointerEnd = (ev) => {
+            handle.releasePointerCapture(ev.pointerId);
+            delete handle.dataset.dragging;
+            handle.removeEventListener('pointermove', onPointerMove);
+            handle.removeEventListener('pointerup', onPointerEnd);
+            handle.removeEventListener('pointercancel', onPointerEnd);
+            // Only persist on drag-end so a quick drag isn't followed by a
+            // burst of writes for every intermediate position.
+            writeStoredSplitRatio(leftRatioRef.current);
+        };
+        handle.addEventListener('pointermove', onPointerMove);
+        handle.addEventListener('pointerup', onPointerEnd);
+        handle.addEventListener('pointercancel', onPointerEnd);
+    }, []);
+    const handleResizerDoubleClick = React.useCallback(() => {
+        setLeftRatio(DEFAULT_SPLIT_RATIO);
+        writeStoredSplitRatio(DEFAULT_SPLIT_RATIO);
+    }, []);
+    if (loading) {
+        return React.createElement("div", { className: "jp-xtralab-DiffWidget-status" }, "Loading diff\u2026");
+    }
+    if (error !== null) {
+        return (React.createElement("div", { className: "jp-xtralab-DiffWidget-status", "data-error": "true" }, error));
+    }
+    if (isBinary) {
+        return (React.createElement("div", { className: "jp-xtralab-DiffWidget-status" }, "Binary file \u2014 diff not supported."));
+    }
+    if (imageType !== null) {
+        // `oldText`/`newText` carry the two revisions as base64 here. The
+        // image view owns its own layout and mode selector, so it does not
+        // use the split resizer or the notebook/JSON toggle.
+        return (React.createElement("div", { className: "jp-xtralab-DiffWidget-content" },
+            React.createElement(ImageDiffView, { reference: oldText, challenger: newText, fileType: imageType })));
+    }
+    // Decide which view to render. The notebook view requires a successful
+    // nbformat parse; if that failed, we only show the raw JSON file diff.
+    const hasNotebookView = notebookDiff !== null;
+    const showNotebookView = hasNotebookView && notebookViewMode === 'notebook';
+    const showFileDiff = !showNotebookView && metadata !== null;
+    if (!showNotebookView && !showFileDiff) {
+        return (React.createElement("div", { className: "jp-xtralab-DiffWidget-status" }, "No content to diff."));
+    }
+    // Custom property set on the diffs-container host. The library's
+    // shadow-root rule consumes it via `var(--xtralab-split-cols, …)` (see
+    // SPLIT_RESIZE_CSS) and recomputes the column tracks instantly. Only
+    // relevant in the file-diff path; the notebook view doesn't use it.
+    const leftPercent = leftRatio * 100;
+    const hostStyle = {
+        '--xtralab-split-cols': `${leftPercent}% ${100 - leftPercent}%`
+    };
+    return (React.createElement("div", { className: "jp-xtralab-DiffWidget-content" },
+        React.createElement("div", { ref: wrapperRef, className: "jp-xtralab-DiffWidget-body" },
+            React.createElement("div", { className: "jp-xtralab-DiffWidget-scroll" }, showNotebookView && notebookDiff !== null ? (React.createElement(NotebookDiffView, { diff: notebookDiff, dark: dark, rendermime: rendermime })) : showFileDiff && metadata !== null ? (React.createElement(FileDiff, { fileDiff: metadata, lineAnnotations: lineAnnotations, renderAnnotation: renderAnnotation, style: hostStyle, 
+                // Disable the worker pool: JupyterLab's webpack federation
+                // pipeline doesn't ship the library's
+                // `@pierre/diffs/worker/worker.js` file at a URL the worker
+                // bootstrap can resolve from, so leaving the pool enabled
+                // crashes on instantiation. Running on the main thread is
+                // fine for the small files git diffs typically operate on.
+                disableWorkerPool: true, options: {
+                    diffStyle: 'split',
+                    // Drop the file header — the tab title already shows the
+                    // file name and the panel header carries the change
+                    // context.
+                    disableFileHeader: true,
+                    theme: dark ? 'pierre-dark' : 'pierre-light',
+                    themeType: dark ? 'dark' : 'light',
+                    // Inject the column-resize override into the shadow root
+                    // via the library's `@layer unsafe` channel. Keeping the
+                    // string constant lets the library short-circuit the
+                    // re-render path it uses when this option actually
+                    // changes.
+                    unsafeCSS: SPLIT_RESIZE_CSS
+                } })) : null),
+            showFileDiff ? (React.createElement("div", { className: "jp-xtralab-DiffWidget-resizer", style: { left: `${leftPercent}%` }, role: "separator", "aria-orientation": "vertical", "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)", onPointerDown: handleResizerPointerDown, onDoubleClick: handleResizerDoubleClick })) : null)));
+}
+/**
+ * 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 function NotebookViewModeControl(props) {
+    const { mode, available, onChange } = props;
+    if (!available) {
+        return React.createElement(React.Fragment, null);
+    }
+    return (React.createElement("div", { className: "jp-xtralab-DiffWidget-segmented", role: "tablist", "aria-label": "Notebook diff view mode" },
+        React.createElement("button", { type: "button", role: "tab", "aria-selected": mode === 'notebook', "data-active": mode === 'notebook', className: "jp-xtralab-DiffWidget-segmentedButton", onClick: () => onChange('notebook') }, "Notebook"),
+        React.createElement("button", { type: "button", role: "tab", "aria-selected": mode === 'json', "data-active": mode === 'json', className: "jp-xtralab-DiffWidget-segmentedButton", onClick: () => onChange('json') }, "JSON")));
+}

package/lib/git/diffWidget.d.ts

@@ -4,21 +4,11 @@ import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import { Contents } from '@jupyterlab/services';
 import { ReactWidget } from '@jupyterlab/ui-components';
 import { ISignal } from '@lumino/signaling';
+import { DIFF_WIDGET_CSS_CLASS, type NotebookDiffViewMode } from './diffSurface';
 import { GitReference, IFileChange } from './tokens';
-/**
- * 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";
+export { DIFF_WIDGET_CSS_CLASS };
 export declare const PREVIEW_DIFF_WIDGET_ID = "xtralab:diff:preview";
 export declare function pinnedDiffWidgetId(change: IFileChange): string;
-/**
- * View modes available for `.ipynb` diffs. `notebook` is the cell-by-cell
- * rendered view; `json` falls back to the raw nbformat JSON file diff so
- * the user can inspect exactly which bytes changed (handy for nbformat
- * spelunking, seeing execution_count drift, etc.).
- */
-type NotebookDiffViewMode = 'notebook' | 'json';
 /**
  * Build the deterministic widget id used for a diff against a particular
  * file/group pair. Reused across plugin and command code so reopening a
@@ -69,6 +59,12 @@ export interface IGitDiffWidgetOptions {
  * usual document chrome — toolbar slot, focus tracker integration, and
  * spinner-while-loading hooks — and matches the pattern used for other
  * read-only main-area widgets in the JupyterLab ecosystem.
+ *
+ * This is the launcher dashboard's own diff path
+ * (`xtralab:git:open-diff`), kept independent of `jupyterlab-git`. The
+ * actual diff rendering is delegated to the shared {@link DiffSurface};
+ * `jupyterlab-git`'s panel reaches the same surface through the providers
+ * registered in `diffProvider.tsx`.
  */
 export declare function createGitDiffWidget(options: IGitDiffWidgetOptions): MainAreaWidget<DiffContentWidget>;
 export declare function updateGitDiffWidget(widget: MainAreaWidget<DiffContentWidget>, change: IFileChange): void;
@@ -116,4 +112,3 @@ export declare class DiffContentWidget extends ReactWidget {
     private _pinned;
     private _pinnedChanged;
 }
-export {};