xtralab 0.15.0 → 0.15.1

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;
 }
 /**

package/lib/git/diffWidget.js

@@ -31,6 +31,9 @@ export class XtralabDiffWidget extends ReactWidget {
         this.addClass('jp-git-diff-root');
         this.addClass(DIFF_WIDGET_CSS_CLASS);
     }
+    /**
+     * The git diff model being rendered.
+     */
     get model() {
         return this._model;
     }
@@ -74,9 +77,15 @@ export class XtralabDiffWidget extends ReactWidget {
         this.update();
         await done.promise;
     }
+    /**
+     * The current rendered-vs-JSON choice for notebook diffs.
+     */
     get notebookViewMode() {
         return this._notebookViewMode;
     }
+    /**
+     * Set the notebook view mode and persist it.
+     */
     setNotebookViewMode(mode) {
         if (mode === this._notebookViewMode) {
             return;
@@ -85,12 +94,21 @@ export class XtralabDiffWidget extends ReactWidget {
         writeStoredNotebookViewMode(mode);
         this._notebookViewModeChanged.emit(mode);
     }
+    /**
+     * A signal emitted when the notebook view mode changes.
+     */
     get notebookViewModeChanged() {
         return this._notebookViewModeChanged;
     }
+    /**
+     * Whether a rendered notebook view is currently available.
+     */
     get hasNotebookView() {
         return this._hasNotebookView;
     }
+    /**
+     * Set whether a rendered notebook view is available.
+     */
     setHasNotebookView(value) {
         if (value === this._hasNotebookView) {
             return;
@@ -98,12 +116,21 @@ export class XtralabDiffWidget extends ReactWidget {
         this._hasNotebookView = value;
         this._hasNotebookViewChanged.emit(value);
     }
+    /**
+     * A signal emitted when rendered-notebook availability changes.
+     */
     get hasNotebookViewChanged() {
         return this._hasNotebookViewChanged;
     }
+    /**
+     * The current split/unified layout for textual file diffs.
+     */
     get diffStyle() {
         return this._diffStyle;
     }
+    /**
+     * Set the diff style and persist it.
+     */
     setDiffStyle(style) {
         if (style === this._diffStyle) {
             return;
@@ -112,6 +139,9 @@ export class XtralabDiffWidget extends ReactWidget {
         writeStoredDiffStyle(style);
         this._diffStyleChanged.emit(style);
     }
+    /**
+     * A signal emitted when the diff style changes.
+     */
     get diffStyleChanged() {
         return this._diffStyleChanged;
     }
@@ -121,6 +151,9 @@ export class XtralabDiffWidget extends ReactWidget {
     get fileDiffActive() {
         return this._fileDiffActive;
     }
+    /**
+     * Set whether the textual file diff is the active view.
+     */
     setFileDiffActive(value) {
         if (value === this._fileDiffActive) {
             return;
@@ -128,6 +161,9 @@ export class XtralabDiffWidget extends ReactWidget {
         this._fileDiffActive = value;
         this._fileDiffActiveChanged.emit(value);
     }
+    /**
+     * A signal emitted when {@link fileDiffActive} changes.
+     */
     get fileDiffActiveChanged() {
         return this._fileDiffActiveChanged;
     }
@@ -137,27 +173,44 @@ export class XtralabDiffWidget extends ReactWidget {
     get emptied() {
         return this._emptied;
     }
+    /**
+     * Emit the {@link emptied} signal.
+     */
     notifyEmptied() {
         this._emptied.emit();
     }
+    /**
+     * Resolve and clear the pending `refresh()` promise, if any.
+     */
     settleRefresh() {
         const pending = this._pendingRefresh;
         this._pendingRefresh = null;
         pending === null || pending === void 0 ? void 0 : pending.resolve();
     }
+    /**
+     * Dispose of the resources held by the widget.
+     */
     dispose() {
-        // Release any in-flight refresh awaiter so a host that awaits refresh()
-        // (jupyterlab-git re-shows its diff button only once it resolves) does not
-        // hang when the widget is torn down mid-fetch.
+        // jupyterlab-git awaits refresh() to re-show its diff button; release any
+        // in-flight awaiter so it does not hang on mid-fetch teardown.
         this.settleRefresh();
         super.dispose();
     }
+    /**
+     * A counter incremented on each `refresh()` to trigger a content re-fetch.
+     */
     get reloadNonce() {
         return this._reloadNonce;
     }
+    /**
+     * The application-level services used by the rendered diff.
+     */
     get context() {
         return this._context;
     }
+    /**
+     * Render the diff view for the current model.
+     */
     render() {
         return React.createElement(ModelDiffView, { widget: this });
     }
@@ -174,7 +227,6 @@ function ModelDiffView(props) {
         newText: '',
         error: null
     });
-    // Mirror toolbar-driven notebook view changes into React state.
     const [notebookViewMode, setNotebookViewMode] = React.useState(() => widget.notebookViewMode);
     React.useEffect(() => {
         const handler = (sender, mode) => {
@@ -189,7 +241,6 @@ function ModelDiffView(props) {
     const handleNotebookAvailabilityChange = React.useCallback((available) => {
         widget.setHasNotebookView(available);
     }, [widget]);
-    // Mirror toolbar-driven diff-style changes into React state.
     const [diffStyle, setDiffStyle] = React.useState(() => widget.diffStyle);
     React.useEffect(() => {
         const handler = (sender, style) => {
@@ -226,18 +277,14 @@ function ModelDiffView(props) {
             observer.disconnect();
         };
     }, [themeManager]);
-    // Image diffs use the server's base64 payloads; other binaries show a placeholder.
     const isImage = React.useMemo(() => imageDataType(model.filename) !== null, [model.filename]);
     const isBinary = model.isBinary === true && !isImage;
-    // Used by the launcher to auto-close an emptied diff after discard.
     const [hunkCount, setHunkCount] = React.useState(null);
     const handleMetadataChange = React.useCallback((info) => {
         setHunkCount(info.hunkCount);
     }, []);
-    // Fetch both sides whenever the model or reload nonce changes.
     React.useEffect(() => {
         let cancelled = false;
-        // Non-image binaries do not need content fetches.
         if (isBinary) {
             setState({ loading: false, oldText: '', newText: '', error: null });
             // An in-flight `refresh()` still has to resolve.
@@ -276,7 +323,6 @@ function ModelDiffView(props) {
             }
             finally {
                 if (!cancelled) {
-                    // Let `refresh()` settle once content has loaded.
                     widget.settleRefresh();
                 }
             }
@@ -295,7 +341,6 @@ function ModelDiffView(props) {
             widget.notifyEmptied();
         }
     }, [state.loading, state.error, isBinary, hunkCount, nonce, widget]);
-    // The launcher sets `canDiscard`; jupyterlab-git models fall back to source.
     const canDiscardHunk = (_a = model.canDiscard) !== null && _a !== void 0 ? _a : (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]);
@@ -309,7 +354,6 @@ function ModelDiffView(props) {
             });
         },
         onAfterSave: () => {
-            // Re-pull so the diff reflects the reverted hunk.
             void widget.refresh();
         }
     }), [canDiscardHunk, contentsManager, serverPath, widget]);
@@ -339,6 +383,9 @@ class NotebookViewModeToolbarItem extends ReactWidget {
         this._widget = widget;
         this.addClass('jp-xtralab-DiffWidget-viewModeToolbarItem');
     }
+    /**
+     * Render the Notebook/JSON toggle.
+     */
     render() {
         return React.createElement(NotebookViewModeToolbarControl, { widget: this._widget });
     }
@@ -375,6 +422,9 @@ class DiffStyleToolbarItem extends ReactWidget {
         this._widget = widget;
         this.addClass('jp-xtralab-DiffWidget-diffStyleToolbarItem');
     }
+    /**
+     * Render the Split/Unified toggle.
+     */
     render() {
         return React.createElement(DiffStyleToolbarControl, { widget: this._widget });
     }

package/lib/git/imageDiff.d.ts

@@ -1,14 +1,14 @@
 import * as React from 'react';
 import type { TranslationBundle } from '@jupyterlab/translation';
-/**
- * The file extensions registered as the xtralab image diff provider.
- */
 export declare const IMAGE_DIFF_EXTENSIONS: string[];
 /**
  * The `data:` MIME subtype for a path xtralab renders as an image, or
  * `null` when the path is not a supported raster image.
  */
 export declare function imageDataType(path: string): string | null;
+/**
+ * Props for {@link ImageDiffView}.
+ */
 interface IImageDiffViewProps {
     /**
      * Base64 of the reference (old) revision; empty when added.
@@ -28,9 +28,8 @@ interface IImageDiffViewProps {
     trans: TranslationBundle;
 }
 /**
- * The image comparison surface: a segmented mode selector (reusing the
- * diff segmented-control styling so it matches the Notebook/JSON toggle)
- * plus the selected 2-up / swipe / onion-skin view.
+ * The image comparison surface: a mode selector (reusing the diff widget's
+ * segmented-control styling) plus the selected 2-up / swipe / onion view.
  */
 export declare function ImageDiffView(props: IImageDiffViewProps): React.ReactElement;
 export {};

package/lib/git/imageDiff.js

@@ -1,20 +1,14 @@
 import * as React from 'react';
 /**
  * xtralab's image diff, registered in place of `@jupyterlab/git:image-diff`.
- *
- * The git server base64-encodes binary content, so both diff hosts receive
- * the two sides as base64 strings through the same `content()` getters used
- * for text. This module turns those strings into `<img>` elements and
- * offers the 2-up / swipe / onion-skin comparison modes; no diffing library
- * is involved (`@pierre/diffs` is text-only).
+ * Both sides arrive base64-encoded through the same `content()` getters used
+ * for text; the 2-up/swipe/onion views are hand-rolled (`@pierre/diffs` is
+ * text-only).
  */
 /**
- * Raster image extensions xtralab renders as an image diff, mapped to the
- * MIME subtype used in the `data:image/<subtype>;base64,…` URL.
- *
- * `.svg` is intentionally absent: it is XML text, so the `@pierre/diffs`
- * text diff (the fallback provider) is more useful for it than an image
- * comparison.
+ * Raster extensions mapped to the `data:image/<subtype>` MIME subtype.
+ * `.svg` is intentionally absent: it is XML text, so the fallback text diff
+ * is more useful than an image comparison.
  */
 const IMAGE_DATA_TYPES = {
     '.png': 'png',
@@ -25,9 +19,6 @@ const IMAGE_DATA_TYPES = {
     '.bmp': 'bmp',
     '.ico': 'x-icon'
 };
-/**
- * The file extensions registered as the xtralab image diff provider.
- */
 export const IMAGE_DIFF_EXTENSIONS = Object.keys(IMAGE_DATA_TYPES);
 /**
  * The `data:` MIME subtype for a path xtralab renders as an image, or
@@ -51,8 +42,7 @@ function readStoredImageViewMode() {
         }
     }
     catch (_a) {
-        // localStorage can throw in privacy/sandboxed contexts — 2-up is the
-        // sensible default anyway.
+        // localStorage can throw in privacy/sandboxed contexts.
     }
     return '2-up';
 }
@@ -65,17 +55,13 @@ function writeStoredImageViewMode(mode) {
     }
 }
 /**
- * Strip whitespace from a base64 payload. Python's `base64.encodebytes`
- * (used by the git server) inserts a newline every 76 characters; most
- * browsers tolerate that inside a `data:` URL but some are stricter, and
- * the cleaned length also lets us size the file accurately.
+ * Strip whitespace from a base64 payload: the server's `base64.encodebytes`
+ * inserts newlines some browsers reject in `data:` URLs, and the cleaned
+ * length sizes the file accurately.
  */
 function cleanBase64(value) {
     return value.replace(/\s+/g, '');
 }
-/**
- * Decoded byte length of a (whitespace-free) base64 string.
- */
 function base64ByteLength(clean) {
     if (clean.length === 0) {
         return 0;
@@ -107,9 +93,8 @@ function toSide(raw, fileType) {
     };
 }
 /**
- * The image comparison surface: a segmented mode selector (reusing the
- * diff segmented-control styling so it matches the Notebook/JSON toggle)
- * plus the selected 2-up / swipe / onion-skin view.
+ * The image comparison surface: a mode selector (reusing the diff widget's
+ * segmented-control styling) plus the selected 2-up / swipe / onion view.
  */
 export function ImageDiffView(props) {
     const { reference, challenger, fileType, trans } = props;
@@ -157,21 +142,14 @@ function TwoUp({ reference, challenger, trans }) {
             React.createElement("div", { className: "jp-xtralab-ImageDiff-frame", "data-side": "challenger" }, challenger.uri !== null ? (React.createElement("img", { className: "jp-xtralab-ImageDiff-img", src: challenger.uri, alt: trans.__('Challenger revision'), onLoad: onChallLoad })) : (React.createElement("div", { className: "jp-xtralab-ImageDiff-empty" }, trans.__('Deleted')))),
             React.createElement("figcaption", { className: "jp-xtralab-ImageDiff-caption" }, caption(challenger, challSize, trans.__('Deleted'))))));
 }
-/**
- * Range slider shared by the swipe and onion-skin views. A native
- * `<input type="range">` (styled via CSS) keeps the bundle free of a UI
- * component dependency.
- */
 function RangeSlider(props) {
     const { value, onChange, ariaLabel } = props;
     return (React.createElement("input", { className: "jp-xtralab-ImageDiff-slider", type: "range", min: 0, max: 100, step: 1, value: value, "aria-label": ariaLabel, onChange: event => onChange(Number(event.target.value)) }));
 }
 /**
- * Fit a `naturalWidth × naturalHeight` image inside an `areaWidth ×
- * areaHeight` box without upscaling past its intrinsic size — the same
- * "contain, never enlarge" rule the 2-up and onion views get for free from
- * `max-width/height: 100%; width/height: auto`. Returns the displayed pixel
- * box, or `null` until both the image and the area have been measured.
+ * Fit an image inside an area without upscaling past its intrinsic size —
+ * the "contain, never enlarge" rule the other views get from CSS. Returns
+ * the displayed pixel box, or `null` until both sizes are measured.
  */
 function containBox(naturalWidth, naturalHeight, areaWidth, areaHeight) {
     if (naturalWidth <= 0 ||
@@ -183,9 +161,6 @@ function containBox(naturalWidth, naturalHeight, areaWidth, areaHeight) {
     const scale = Math.min(areaWidth / naturalWidth, areaHeight / naturalHeight, 1);
     return { width: naturalWidth * scale, height: naturalHeight * scale };
 }
-/**
- * Track an element's content-box size, kept current across layout changes.
- */
 function useElementSize() {
     const ref = React.useRef(null);
     const [size, setSize] = React.useState({ width: 0, height: 0 });
@@ -214,13 +189,9 @@ function Swipe({ reference, challenger, trans }) {
     const [challSize, onChallLoad] = useNaturalSize();
     const [areaRef, area] = useElementSize();
     const frameRef = React.useRef(null);
-    // Display both revisions in a single box — the union of their intrinsic
-    // sizes, scaled down to fit but never enlarged — and size the frame to
-    // exactly that box. The divider's `left: N%`, the pointer-to-percent
-    // mapping (below) and each image's `clip-path` inset then all resolve
-    // against the same width, so the white line sits precisely on the seam
-    // between the two revisions at every position. A full-width frame instead
-    // let the line drift off the seam by as much as half the letterbox.
+    // Size the frame to the union box of both revisions so the divider %, the
+    // pointer mapping and the clip-paths all resolve against the same width;
+    // a full-width frame lets the line drift off the seam.
     const naturalWidth = Math.max((_a = refSize === null || refSize === void 0 ? void 0 : refSize[0]) !== null && _a !== void 0 ? _a : 0, (_b = challSize === null || challSize === void 0 ? void 0 : challSize[0]) !== null && _b !== void 0 ? _b : 0);
     const naturalHeight = Math.max((_c = refSize === null || refSize === void 0 ? void 0 : refSize[1]) !== null && _c !== void 0 ? _c : 0, (_d = challSize === null || challSize === void 0 ? void 0 : challSize[1]) !== null && _d !== void 0 ? _d : 0);
     const box = containBox(naturalWidth, naturalHeight, area.width, area.height);
@@ -237,7 +208,6 @@ function Swipe({ reference, challenger, trans }) {
         setPosition(Math.max(0, Math.min(100, next)));
     }, []);
     const onPointerDown = React.useCallback((event) => {
-        // Only react to the primary pointer (left click / touch / pen tip).
         if (event.button !== 0) {
             return;
         }

package/lib/git/index.d.ts

@@ -1,8 +1,5 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 import { CommandArguments, CommandIDs } from './commands';
-/**
- * Plugins contributed by xtralab's git integration.
- */
 declare const plugins: JupyterFrontEndPlugin<unknown>[];
 export { CommandArguments, CommandIDs };
 export default plugins;

package/lib/git/index.js

@@ -7,10 +7,9 @@ import diffProviderPlugin from './diffProvider';
 const GIT_DIFF_COMMAND_PLUGIN_ID = 'xtralab:git-diff-command';
 const GIT_DIFF_TRACKER_NAMESPACE = 'xtralab-git-diff';
 /**
- * The launcher's git diff command plugin.
- *
- * The upstream git panel stays enabled; this plugin only gives the launcher
- * its own `xtralab:git:open-diff` command and preview/pinned-tab tracking.
+ * The launcher's git diff command plugin. The upstream git panel stays
+ * enabled; this only adds `xtralab:git:open-diff` and preview/pinned-tab
+ * tracking.
  */
 const diffCommandPlugin = {
     id: GIT_DIFF_COMMAND_PLUGIN_ID,
@@ -19,7 +18,6 @@ const diffCommandPlugin = {
     optional: [IThemeManager, IRenderMimeRegistry, ITranslator, IAskAgent],
     activate: (app, themeManager, rendermime, translator, askAgent) => {
         const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
-        // Track open diffs so repeated opens reveal the existing tab.
         const tracker = new WidgetTracker({
             namespace: GIT_DIFF_TRACKER_NAMESPACE
         });
@@ -53,9 +51,6 @@ const diffCommandPlugin = {
         });
     }
 };
-/**
- * Plugins contributed by xtralab's git integration.
- */
 const plugins = [
     diffCommandPlugin,
     diffProviderPlugin