xtralab 0.14.1 → 0.15.1

package/src/git/diffWidget.tsx

@@ -37,8 +37,17 @@ 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;
 }
 
@@ -46,14 +55,27 @@ export interface IXtralabDiffModel extends Git.Diff.IModel {
  * 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;
 }
 
@@ -75,6 +97,9 @@ export class XtralabDiffWidget
     this.addClass(DIFF_WIDGET_CSS_CLASS);
   }
 
+  /**
+   * The git diff model being rendered.
+   */
   get model(): Git.Diff.IModel {
     return this._model;
   }
@@ -124,10 +149,16 @@ export class XtralabDiffWidget
     await done.promise;
   }
 
+  /**
+   * The current rendered-vs-JSON choice for notebook diffs.
+   */
   get notebookViewMode(): NotebookDiffViewMode {
     return this._notebookViewMode;
   }
 
+  /**
+   * Set the notebook view mode and persist it.
+   */
   setNotebookViewMode(mode: NotebookDiffViewMode): void {
     if (mode === this._notebookViewMode) {
       return;
@@ -137,14 +168,23 @@ export class XtralabDiffWidget
     this._notebookViewModeChanged.emit(mode);
   }
 
+  /**
+   * A signal emitted when the notebook view mode changes.
+   */
   get notebookViewModeChanged(): ISignal<this, NotebookDiffViewMode> {
     return this._notebookViewModeChanged;
   }
 
+  /**
+   * Whether a rendered notebook view is currently available.
+   */
   get hasNotebookView(): boolean {
     return this._hasNotebookView;
   }
 
+  /**
+   * Set whether a rendered notebook view is available.
+   */
   setHasNotebookView(value: boolean): void {
     if (value === this._hasNotebookView) {
       return;
@@ -153,14 +193,23 @@ export class XtralabDiffWidget
     this._hasNotebookViewChanged.emit(value);
   }
 
+  /**
+   * A signal emitted when rendered-notebook availability changes.
+   */
   get hasNotebookViewChanged(): ISignal<this, boolean> {
     return this._hasNotebookViewChanged;
   }
 
+  /**
+   * The current split/unified layout for textual file diffs.
+   */
   get diffStyle(): DiffStyle {
     return this._diffStyle;
   }
 
+  /**
+   * Set the diff style and persist it.
+   */
   setDiffStyle(style: DiffStyle): void {
     if (style === this._diffStyle) {
       return;
@@ -170,6 +219,9 @@ export class XtralabDiffWidget
     this._diffStyleChanged.emit(style);
   }
 
+  /**
+   * A signal emitted when the diff style changes.
+   */
   get diffStyleChanged(): ISignal<this, DiffStyle> {
     return this._diffStyleChanged;
   }
@@ -181,6 +233,9 @@ export class XtralabDiffWidget
     return this._fileDiffActive;
   }
 
+  /**
+   * Set whether the textual file diff is the active view.
+   */
   setFileDiffActive(value: boolean): void {
     if (value === this._fileDiffActive) {
       return;
@@ -189,6 +244,9 @@ export class XtralabDiffWidget
     this._fileDiffActiveChanged.emit(value);
   }
 
+  /**
+   * A signal emitted when {@link fileDiffActive} changes.
+   */
   get fileDiffActiveChanged(): ISignal<this, boolean> {
     return this._fileDiffActiveChanged;
   }
@@ -200,32 +258,49 @@ export class XtralabDiffWidget
     return this._emptied;
   }
 
+  /**
+   * Emit the {@link emptied} signal.
+   */
   notifyEmptied(): void {
     this._emptied.emit();
   }
 
+  /**
+   * Resolve and clear the pending `refresh()` promise, if any.
+   */
   settleRefresh(): void {
     const pending = this._pendingRefresh;
     this._pendingRefresh = null;
     pending?.resolve();
   }
 
+  /**
+   * Dispose of the resources held by the widget.
+   */
   dispose(): void {
-    // 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(): number {
     return this._reloadNonce;
   }
 
+  /**
+   * The application-level services used by the rendered diff.
+   */
   get context(): IXtralabDiffContext {
     return this._context;
   }
 
+  /**
+   * Render the diff view for the current model.
+   */
   protected render(): React.ReactElement {
     return <ModelDiffView widget={this} />;
   }
@@ -247,10 +322,25 @@ export class XtralabDiffWidget
   private _emptied = new Signal<this, void>(this);
 }
 
+/**
+ * Resolved file-contents state for {@link ModelDiffView}.
+ */
 interface IModelDiffState {
+  /**
+   * Whether the file contents are still being fetched.
+   */
   loading: boolean;
+  /**
+   * The resolved reference-side text.
+   */
   oldText: string;
+  /**
+   * The resolved challenger-side text.
+   */
   newText: string;
+  /**
+   * The fetch error message, or `null` if none.
+   */
   error: string | null;
 }
 
@@ -270,7 +360,6 @@ function ModelDiffView(props: {
     error: null
   });
 
-  // Mirror toolbar-driven notebook view changes into React state.
   const [notebookViewMode, setNotebookViewMode] =
     React.useState<NotebookDiffViewMode>(() => widget.notebookViewMode);
   React.useEffect(() => {
@@ -294,7 +383,6 @@ function ModelDiffView(props: {
     [widget]
   );
 
-  // Mirror toolbar-driven diff-style changes into React state.
   const [diffStyle, setDiffStyle] = React.useState<DiffStyle>(
     () => widget.diffStyle
   );
@@ -343,14 +431,12 @@ function ModelDiffView(props: {
     };
   }, [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<number | null>(null);
   const handleMetadataChange = React.useCallback(
     (info: { hunkCount: number | null }) => {
@@ -359,10 +445,8 @@ function ModelDiffView(props: {
     []
   );
 
-  // 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.
@@ -399,7 +483,6 @@ function ModelDiffView(props: {
         });
       } finally {
         if (!cancelled) {
-          // Let `refresh()` settle once content has loaded.
           widget.settleRefresh();
         }
       }
@@ -422,7 +505,6 @@ function ModelDiffView(props: {
     }
   }, [state.loading, state.error, isBinary, hunkCount, nonce, widget]);
 
-  // The launcher sets `canDiscard`; jupyterlab-git models fall back to source.
   const canDiscardHunk =
     model.canDiscard ??
     (model.challenger.source === Git.Diff.SpecialRef.WORKING &&
@@ -444,7 +526,6 @@ function ModelDiffView(props: {
         });
       },
       onAfterSave: () => {
-        // Re-pull so the diff reflects the reverted hunk.
         void widget.refresh();
       }
     }),
@@ -503,6 +584,9 @@ class NotebookViewModeToolbarItem extends ReactWidget {
     this.addClass('jp-xtralab-DiffWidget-viewModeToolbarItem');
   }
 
+  /**
+   * Render the Notebook/JSON toggle.
+   */
   protected render(): React.ReactElement {
     return <NotebookViewModeToolbarControl widget={this._widget} />;
   }
@@ -561,6 +645,9 @@ class DiffStyleToolbarItem extends ReactWidget {
     this.addClass('jp-xtralab-DiffWidget-diffStyleToolbarItem');
   }
 
+  /**
+   * Render the Split/Unified toggle.
+   */
   protected render(): React.ReactElement {
     return <DiffStyleToolbarControl widget={this._widget} />;
   }
@@ -608,6 +695,9 @@ function DiffStyleToolbarControl(props: {
  * 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/src/git/imageDiff.tsx

@@ -4,21 +4,15 @@ import type { TranslationBundle } from '@jupyterlab/translation';
 
 /**
  * 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: Record<string, string> = {
   '.png': 'png',
@@ -30,9 +24,6 @@ const IMAGE_DATA_TYPES: Record<string, string> = {
   '.ico': 'x-icon'
 };
 
-/**
- * The file extensions registered as the xtralab image diff provider.
- */
 export const IMAGE_DIFF_EXTENSIONS = Object.keys(IMAGE_DATA_TYPES);
 
 /**
@@ -48,9 +39,6 @@ export function imageDataType(path: string): string | null {
   return IMAGE_DATA_TYPES[lower.slice(dot)] ?? null;
 }
 
-/**
- * Comparison layouts, matching jupyterlab-git's image diff modes.
- */
 type ImageDiffViewMode = '2-up' | 'swipe' | 'onion';
 
 const IMAGE_DIFF_VIEW_MODE_STORAGE_KEY = 'xtralab:image-diff-view-mode';
@@ -62,8 +50,7 @@ function readStoredImageViewMode(): ImageDiffViewMode {
       return raw;
     }
   } catch {
-    // localStorage can throw in privacy/sandboxed contexts — 2-up is the
-    // sensible default anyway.
+    // localStorage can throw in privacy/sandboxed contexts.
   }
   return '2-up';
 }
@@ -77,18 +64,14 @@ function writeStoredImageViewMode(mode: ImageDiffViewMode): void {
 }
 
 /**
- * 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: string): string {
   return value.replace(/\s+/g, '');
 }
 
-/**
- * Decoded byte length of a (whitespace-free) base64 string.
- */
 function base64ByteLength(clean: string): number {
   if (clean.length === 0) {
     return 0;
@@ -111,13 +94,25 @@ function formatBytes(bytes: number): string {
   return `${value.toFixed(value < 10 ? 1 : 0)} ${units[unit]}`;
 }
 
+/**
+ * One side of the image comparison, decoded from its base64 payload.
+ */
 interface IImageSide {
   /**
    * Cleaned base64 payload; empty string means the side does not exist.
    */
   data: string;
+  /**
+   * Whether this side exists; added and deleted files lack one side.
+   */
   present: boolean;
+  /**
+   * The `data:` URI for the image, or `null` when the side is absent.
+   */
   uri: string | null;
+  /**
+   * Decoded size of the payload in bytes.
+   */
   bytes: number;
 }
 
@@ -132,6 +127,9 @@ function toSide(raw: string, fileType: string): IImageSide {
   };
 }
 
+/**
+ * Props for {@link ImageDiffView}.
+ */
 interface IImageDiffViewProps {
   /**
    * Base64 of the reference (old) revision; empty when added.
@@ -152,9 +150,8 @@ interface IImageDiffViewProps {
 }
 
 /**
- * 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: IImageDiffViewProps): React.ReactElement {
   const { reference, challenger, fileType, trans } = props;
@@ -217,9 +214,21 @@ export function ImageDiffView(props: IImageDiffViewProps): React.ReactElement {
   );
 }
 
+/**
+ * Props shared by the 2-up, swipe, and onion-skin views.
+ */
 interface ISideViewProps {
+  /**
+   * The reference (old) side.
+   */
   reference: IImageSide;
+  /**
+   * The challenger (new) side.
+   */
   challenger: IImageSide;
+  /**
+   * Translation bundle for user-facing strings.
+   */
   trans: TranslationBundle;
 }
 
@@ -303,11 +312,6 @@ function TwoUp({
   );
 }
 
-/**
- * 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: {
   value: number;
   onChange: (value: number) => void;
@@ -329,11 +333,9 @@ function RangeSlider(props: {
 }
 
 /**
- * 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: number,
@@ -357,9 +359,6 @@ function containBox(
   return { width: naturalWidth * scale, height: naturalHeight * scale };
 }
 
-/**
- * Track an element's content-box size, kept current across layout changes.
- */
 function useElementSize(): readonly [
   React.RefObject<HTMLDivElement>,
   { width: number; height: number }
@@ -396,13 +395,9 @@ function Swipe({
   const [areaRef, area] = useElementSize();
   const frameRef = React.useRef<HTMLDivElement>(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(refSize?.[0] ?? 0, challSize?.[0] ?? 0);
   const naturalHeight = Math.max(refSize?.[1] ?? 0, challSize?.[1] ?? 0);
   const box = containBox(naturalWidth, naturalHeight, area.width, area.height);
@@ -422,7 +417,6 @@ function Swipe({
 
   const onPointerDown = React.useCallback(
     (event: React.PointerEvent<HTMLDivElement>) => {
-      // Only react to the primary pointer (left click / touch / pen tip).
       if (event.button !== 0) {
         return;
       }

package/src/git/index.ts

@@ -23,10 +23,9 @@ 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: JupyterFrontEndPlugin<void> = {
   id: GIT_DIFF_COMMAND_PLUGIN_ID,
@@ -42,7 +41,6 @@ const diffCommandPlugin: JupyterFrontEndPlugin<void> = {
     askAgent: IAskAgent | null
   ): void => {
     const trans = (translator ?? nullTranslator).load('jupyterlab');
-    // Track open diffs so repeated opens reveal the existing tab.
     const tracker = new WidgetTracker<DiffMainAreaWidget>({
       namespace: GIT_DIFF_TRACKER_NAMESPACE
     });
@@ -86,9 +84,6 @@ const diffCommandPlugin: JupyterFrontEndPlugin<void> = {
   }
 };
 
-/**
- * Plugins contributed by xtralab's git integration.
- */
 const plugins: JupyterFrontEndPlugin<unknown>[] = [
   diffCommandPlugin,
   diffProviderPlugin