xtralab 0.14.1 → 0.15.1

package/lib/git/diffSurface.js

@@ -5,35 +5,16 @@ import { diffAcceptRejectHunk, parseDiffFromFile } from '@pierre/diffs';
 import { ImageDiffView, imageDataType } from './imageDiff';
 import { buildNotebookDiff, NotebookDiffView } from './notebookDiff';
 import { resolveDiffTheme } from './diffTheme';
-/**
- * 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.
+ * Injected via the `unsafeCSS` option into the shadow root's `@layer
+ * unsafe`, beating the library's base rule that hardcodes `1fr 1fr`. Reads
+ * `--xtralab-split-cols` set on the host — custom properties cross the
+ * shadow boundary, so resizing needs no re-render.
  */
 const SPLIT_RESIZE_CSS = `pre[data-diff-type="split"][data-overflow="scroll"] {
   grid-template-columns: var(--xtralab-split-cols, 1fr 1fr);
@@ -52,8 +33,7 @@ function readStoredSplitRatio() {
         }
     }
     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.
+        // localStorage can throw in privacy mode or sandboxed contexts.
     }
     return DEFAULT_SPLIT_RATIO;
 }
@@ -66,6 +46,9 @@ function writeStoredSplitRatio(ratio) {
     }
 }
 const DIFF_STYLE_STORAGE_KEY = 'xtralab:diff-style';
+/**
+ * Read the persisted diff style, defaulting to `'split'`.
+ */
 export function readStoredDiffStyle() {
     try {
         const raw = window.localStorage.getItem(DIFF_STYLE_STORAGE_KEY);
@@ -74,10 +57,13 @@ export function readStoredDiffStyle() {
         }
     }
     catch (_a) {
-        // See readStoredSplitRatio — privacy-mode / sandboxed contexts can throw.
+        // See readStoredSplitRatio.
     }
     return 'split';
 }
+/**
+ * Persist the diff style to local storage (best-effort).
+ */
 export function writeStoredDiffStyle(style) {
     try {
         window.localStorage.setItem(DIFF_STYLE_STORAGE_KEY, style);
@@ -87,6 +73,9 @@ export function writeStoredDiffStyle(style) {
     }
 }
 const NOTEBOOK_DIFF_VIEW_MODE_STORAGE_KEY = 'xtralab:notebook-diff-view-mode';
+/**
+ * Read the persisted notebook view mode, defaulting to `'notebook'`.
+ */
 export function readStoredNotebookViewMode() {
     try {
         const raw = window.localStorage.getItem(NOTEBOOK_DIFF_VIEW_MODE_STORAGE_KEY);
@@ -95,11 +84,13 @@ export function readStoredNotebookViewMode() {
         }
     }
     catch (_a) {
-        // See readStoredSplitRatio — privacy-mode / sandboxed contexts can
-        // throw on access. The notebook view is the better default anyway.
+        // See readStoredSplitRatio.
     }
     return 'notebook';
 }
+/**
+ * Persist the notebook view mode to local storage (best-effort).
+ */
 export function writeStoredNotebookViewMode(mode) {
     try {
         window.localStorage.setItem(NOTEBOOK_DIFF_VIEW_MODE_STORAGE_KEY, mode);
@@ -109,21 +100,15 @@ export function writeStoredNotebookViewMode(mode) {
     }
 }
 /**
- * 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.
+ * Extension-only check; a false positive is harmless because
+ * {@link buildNotebookDiff} validates the JSON and the file diff is the fallback.
  */
 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, …).
+ * Dark-theme check via `IThemeManager`, falling back to the
+ * `data-jp-theme-light` body attribute for hosts without the token.
  */
 export function isDarkTheme(themeManager) {
     if (themeManager !== null && themeManager.theme !== null) {
@@ -145,14 +130,10 @@ export function isPierreTheme(themeManager) {
 export function DiffSurface(props) {
     const { loading, error, isBinary, oldText, newText, newName, oldName, dark, pierreTheme, rendermime, notebookViewMode, diffStyle, onNotebookAvailabilityChange, onFileDiffActiveChange, onMetadataChange, hunkDiscard, onLineAsk, trans } = 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).
+    // For raster images the host passes both sides as base64 in oldText/newText.
     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.
+    // Owning the metadata here keeps hunk indexes aligned between FileDiff
+    // and diffAcceptRejectHunk on discard.
     const metadata = React.useMemo(() => {
         if (!hasContent || imageType !== null) {
             return null;
@@ -164,47 +145,31 @@ export function DiffSurface(props) {
         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]);
-    // Decide which view to render. The notebook view requires a successful
-    // nbformat parse; if that failed, we only show the raw JSON file diff.
-    // Computed before the early returns below so the file-diff-active effect
-    // can depend on it without violating the rules of hooks.
+    // Computed before the early returns so the hooks below can depend on
+    // them without breaking the rules of hooks.
     const hasNotebookView = notebookDiff !== null;
     const showNotebookView = hasNotebookView && notebookViewMode === 'notebook';
     const showFileDiff = !showNotebookView && metadata !== null;
-    // The split vs unified choice only affects the textual/code file diff, so
-    // tell the host whether that view is active to drive its Split/Unified
-    // toolbar toggle.
     React.useEffect(() => {
         onFileDiffActiveChange === null || onFileDiffActiveChange === void 0 ? void 0 : onFileDiffActiveChange(showFileDiff);
     }, [onFileDiffActiveChange, showFileDiff]);
-    // 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.
+    // Drag listeners read the live ratio from a ref to avoid stale captures.
     const leftRatioRef = React.useRef(leftRatio);
     React.useEffect(() => {
         leftRatioRef.current = leftRatio;
@@ -216,8 +181,6 @@ export function DiffSurface(props) {
         }
         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 }
         }));
@@ -227,12 +190,8 @@ export function DiffSurface(props) {
             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.
+        // additionLines holds the full new file with the hunk reverted; lines keep
+        // their trailing `\n` (lookbehind split), so join('') rebuilds it verbatim.
         const text = updated.additionLines.join('');
         try {
             await hunkDiscard.save(text);
@@ -256,15 +215,11 @@ export function DiffSurface(props) {
         if (onLineAsk === undefined) {
             return;
         }
-        // Anchor to the gutter "+" button that was just clicked. It lives in
-        // the `@pierre/diffs` shadow root (which is open), parked on the
-        // hovered/selected line's number element.
+        // Anchor to the just-clicked gutter "+" button inside the library's open shadow root.
         const slot = (_c = (_b = (_a = wrapperRef.current) === null || _a === void 0 ? void 0 : _a.querySelector('diffs-container')) === null || _b === void 0 ? void 0 : _b.shadowRoot) === null || _c === void 0 ? void 0 : _c.querySelector('[data-gutter-utility-slot]');
         onLineAsk(range, slot instanceof Element ? slot.getBoundingClientRect() : null);
     }, [onLineAsk]);
     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;
         }
@@ -293,8 +248,6 @@ export function DiffSurface(props) {
             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);
@@ -340,19 +293,12 @@ export function DiffSurface(props) {
         return (React.createElement("div", { className: "jp-xtralab-DiffWidget-status" }, trans.__('Binary file — 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, trans: trans })));
     }
     if (!showNotebookView && !showFileDiff) {
         return (React.createElement("div", { className: "jp-xtralab-DiffWidget-status" }, trans.__('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}%`
@@ -360,29 +306,15 @@ export function DiffSurface(props) {
     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, pierreTheme: pierreTheme, rendermime: rendermime, trans: trans })) : 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.
+                // JupyterLab's federation pipeline can't serve the worker bundle
+                // at a resolvable URL, so the pool crashes; run on the main thread.
                 disableWorkerPool: true, options: {
                     diffStyle,
-                    // Drop the file header — the tab title already shows the
-                    // file name and the panel header carries the change
-                    // context.
                     disableFileHeader: true,
                     theme: resolveDiffTheme(dark, pierreTheme),
                     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.
+                    // Constant string lets the library skip its unsafeCSS re-render path.
                     unsafeCSS: SPLIT_RESIZE_CSS,
-                    // Line selection + the gutter "+" button feed the
-                    // ask-agent popup; only wired up when a handler exists so
-                    // a plain diff keeps its passive gutter.
                     ...(onLineAsk !== undefined
                         ? {
                             enableLineSelection: true,
@@ -394,10 +326,8 @@ export function DiffSurface(props) {
             showFileDiff && diffStyle === 'split' ? (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), "aria-label": trans.__('Resize the diff panes'), tabIndex: 0, title: trans.__('Drag to resize the diff panes (double-click to reset)'), onPointerDown: handleResizerPointerDown, onDoubleClick: handleResizerDoubleClick, onKeyDown: handleResizerKeyDown })) : 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}.
+ * Segmented Notebook/JSON selector. Hosts mount it into their own toolbar
+ * and drive value/visibility from the state they pass to {@link DiffSurface}.
  */
 export function NotebookViewModeControl(props) {
     const { mode, available, onChange, trans } = props;
@@ -409,11 +339,9 @@ export function NotebookViewModeControl(props) {
         React.createElement("button", { type: "button", role: "tab", "aria-selected": mode === 'json', "data-active": mode === 'json', className: "jp-xtralab-DiffWidget-segmentedButton", onClick: () => onChange('json') }, trans.__('JSON'))));
 }
 /**
- * Split / unified glyphs, inlined from the `@pierre/diffs` icon sprite
- * (`diffs-icon-diff-split` / `diffs-icon-diff-unified`) so the toggle looks
- * like the one on the library's own docs site without depending on the
- * sprite sheet being injected into the document. `currentColor` lets the
- * segmented-button styling drive the fill (including the active state).
+ * Split / unified glyphs inlined from the `@pierre/diffs` icon sprite so
+ * the toggle matches the library's docs site without the sprite sheet;
+ * `currentColor` lets the button styling drive the fill.
  */
 function DiffSplitIcon() {
     return (React.createElement("svg", { viewBox: "0 0 16 16", fill: "currentColor", "aria-hidden": "true" },
@@ -426,11 +354,8 @@ function DiffUnifiedIcon() {
         React.createElement("path", { fillRule: "evenodd", d: "M14 0a2 2 0 0 1 2 2v5.5H0V2a2 2 0 0 1 2-2zM6.5 3.5a.5.5 0 0 0 0 1h3a.5.5 0 0 0 0-1z", clipRule: "evenodd", opacity: ".4" })));
 }
 /**
- * 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`.
+ * Segmented Split/Unified selector; mirrors {@link NotebookViewModeControl}.
+ * `available` mirrors the surface's `onFileDiffActiveChange`.
  */
 export function DiffStyleControl(props) {
     const { diffStyle, available, onChange, trans } = props;

package/lib/git/diffWidget.d.ts

@@ -14,22 +14,44 @@ 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;
 }
 /**
  * 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 application translation bundle.
+     */
     trans: TranslationBundle;
 }
 /**
@@ -37,6 +59,9 @@ export interface IXtralabDiffContext {
  */
 export declare class XtralabDiffWidget extends ReactWidget implements Git.Diff.IDiffWidget {
     constructor(model: Git.Diff.IModel, context: IXtralabDiffContext);
+    /**
+     * The git diff model being rendered.
+     */
     get model(): Git.Diff.IModel;
     /**
      * Swap the rendered model when the launcher reuses its preview tab.
@@ -54,30 +79,81 @@ export declare class XtralabDiffWidget extends ReactWidget implements Git.Diff.I
      * Re-pull both sides of the model and re-render.
      */
     refresh(): Promise<void>;
+    /**
+     * The current rendered-vs-JSON choice for notebook diffs.
+     */
     get notebookViewMode(): NotebookDiffViewMode;
+    /**
+     * Set the notebook view mode and persist it.
+     */
     setNotebookViewMode(mode: NotebookDiffViewMode): void;
+    /**
+     * A signal emitted when the notebook view mode changes.
+     */
     get notebookViewModeChanged(): ISignal<this, NotebookDiffViewMode>;
+    /**
+     * Whether a rendered notebook view is currently available.
+     */
     get hasNotebookView(): boolean;
+    /**
+     * Set whether a rendered notebook view is available.
+     */
     setHasNotebookView(value: boolean): void;
+    /**
+     * A signal emitted when rendered-notebook availability changes.
+     */
     get hasNotebookViewChanged(): ISignal<this, boolean>;
+    /**
+     * The current split/unified layout for textual file diffs.
+     */
     get diffStyle(): DiffStyle;
+    /**
+     * Set the diff style and persist it.
+     */
     setDiffStyle(style: DiffStyle): void;
+    /**
+     * A signal emitted when the diff style changes.
+     */
     get diffStyleChanged(): ISignal<this, DiffStyle>;
     /**
      * Whether the Split/Unified toolbar selector currently applies.
      */
     get fileDiffActive(): boolean;
+    /**
+     * Set whether the textual file diff is the active view.
+     */
     setFileDiffActive(value: boolean): void;
+    /**
+     * A signal emitted when {@link fileDiffActive} changes.
+     */
     get fileDiffActiveChanged(): ISignal<this, boolean>;
     /**
      * Emitted when a post-discard reload leaves the diff with no hunks.
      */
     get emptied(): ISignal<this, void>;
+    /**
+     * Emit the {@link emptied} signal.
+     */
     notifyEmptied(): void;
+    /**
+     * Resolve and clear the pending `refresh()` promise, if any.
+     */
     settleRefresh(): void;
+    /**
+     * Dispose of the resources held by the widget.
+     */
     dispose(): void;
+    /**
+     * A counter incremented on each `refresh()` to trigger a content re-fetch.
+     */
     get reloadNonce(): number;
+    /**
+     * The application-level services used by the rendered diff.
+     */
     get context(): IXtralabDiffContext;
+    /**
+     * Render the diff view for the current model.
+     */
     protected render(): React.ReactElement;
     private _model;
     private _context;
@@ -97,6 +173,9 @@ export declare class XtralabDiffWidget extends ReactWidget implements Git.Diff.I
  * 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;
 }
 /**