xtralab 0.14.1 → 0.15.1

package/src/git/diffSurface.tsx

@@ -22,38 +22,19 @@ import {
 } 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);
@@ -74,8 +55,7 @@ function readStoredSplitRatio(): number {
       return parsed;
     }
   } catch {
-    // 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;
 }
@@ -88,15 +68,13 @@ function writeStoredSplitRatio(ratio: number): void {
   }
 }
 
-/**
- * Layout for textual/code diffs, forwarded to `@pierre/diffs` as its
- * `diffStyle` option. `split` is the side-by-side old|new view; `unified`
- * is the single-column inline view (what diffs.com calls "stacked").
- */
 export type DiffStyle = 'split' | 'unified';
 
 const DIFF_STYLE_STORAGE_KEY = 'xtralab:diff-style';
 
+/**
+ * Read the persisted diff style, defaulting to `'split'`.
+ */
 export function readStoredDiffStyle(): DiffStyle {
   try {
     const raw = window.localStorage.getItem(DIFF_STYLE_STORAGE_KEY);
@@ -104,11 +82,14 @@ export function readStoredDiffStyle(): DiffStyle {
       return raw;
     }
   } catch {
-    // 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: DiffStyle): void {
   try {
     window.localStorage.setItem(DIFF_STYLE_STORAGE_KEY, style);
@@ -117,15 +98,13 @@ export function writeStoredDiffStyle(style: DiffStyle): void {
   }
 }
 
-/**
- * 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';
 
 const NOTEBOOK_DIFF_VIEW_MODE_STORAGE_KEY = 'xtralab:notebook-diff-view-mode';
 
+/**
+ * Read the persisted notebook view mode, defaulting to `'notebook'`.
+ */
 export function readStoredNotebookViewMode(): NotebookDiffViewMode {
   try {
     const raw = window.localStorage.getItem(
@@ -135,12 +114,14 @@ export function readStoredNotebookViewMode(): NotebookDiffViewMode {
       return raw;
     }
   } catch {
-    // 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: NotebookDiffViewMode): void {
   try {
     window.localStorage.setItem(NOTEBOOK_DIFF_VIEW_MODE_STORAGE_KEY, mode);
@@ -150,31 +131,26 @@ export function writeStoredNotebookViewMode(mode: NotebookDiffViewMode): void {
 }
 
 /**
- * Annotation payload threaded through the diff library back into the
- * `renderAnnotation` callback. Carries the index of the hunk a particular
- * action button targets.
+ * Annotation payload threaded back into `renderAnnotation`; carries the target hunk index.
  */
 interface IHunkActionAnnotation {
+  /**
+   * The index of the hunk the action targets.
+   */
   hunkIndex: number;
 }
 
 /**
- * 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: string): boolean {
   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: IThemeManager | null): boolean {
   if (themeManager !== null && themeManager.theme !== null) {
@@ -192,19 +168,27 @@ export function isPierreTheme(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}.
+ * Per-hunk discard wiring: discarding rebuilds the full file text and the
+ * host owns the write via `save`, then refreshes in `onAfterSave`.
  */
 interface IHunkDiscard {
+  /**
+   * Whether hunk discarding is available.
+   */
   enabled: boolean;
+  /**
+   * Persist the full post-discard file text.
+   */
   save: (fullText: string) => Promise<void>;
+  /**
+   * Called after a successful save so the host can refresh the diff.
+   */
   onAfterSave: () => void;
 }
 
+/**
+ * The props for the {@link DiffSurface} component.
+ */
 interface IDiffSurfaceProps {
   /**
    * Whether the host is still resolving the file contents.
@@ -227,13 +211,11 @@ interface IDiffSurfaceProps {
    */
   newText: string;
   /**
-   * New-side path. Drives notebook detection and the `@pierre/diffs` file
-   * name on the additions side.
+   * New-side path; drives notebook detection and the highlighting filename.
    */
   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.
+   * Old-side path; differs from {@link newName} only for renames.
    */
   oldName?: string;
   /**
@@ -245,35 +227,28 @@ interface IDiffSurfaceProps {
    */
   pierreTheme: 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.
+   * Used by the notebook view; `null` in stripped-down hosts, which forces a textual fallback.
    */
   rendermime: IRenderMimeRegistry | null;
   /**
-   * Current rendered-vs-JSON choice for notebook diffs (host-controlled).
+   * Rendered-vs-JSON choice for notebook diffs (host-controlled).
    */
   notebookViewMode: NotebookDiffViewMode;
   /**
-   * Split vs unified layout for the textual/code file diff (host-controlled).
+   * Split vs unified layout for the textual file diff (host-controlled).
    */
   diffStyle: DiffStyle;
   /**
-   * Called whenever the availability of a rendered notebook view changes,
-   * so the host can show/hide its Notebook/JSON toolbar toggle.
+   * Fires when rendered-notebook availability changes so the host can toggle its Notebook/JSON control.
    */
   onNotebookAvailabilityChange?: (available: boolean) => void;
   /**
-   * Called whenever the textual/code file diff (the only view the split vs
-   * unified choice affects) becomes the active view, so the host can
-   * show/hide its Split/Unified toolbar toggle. False for image, binary,
-   * rendered-notebook, loading and error states.
+   * Fires when the textual file diff becomes (in)active — the only view the split/unified choice affects.
    */
   onFileDiffActiveChange?: (active: 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.
+   * Fires after each diff computation with the hunk count (`null` when no
+   * textual diff); hosts use it to auto-close emptied diffs.
    */
   onMetadataChange?: (info: { hunkCount: number | null }) => void;
   /**
@@ -281,11 +256,8 @@ interface IDiffSurfaceProps {
    */
   hunkDiscard?: IHunkDiscard;
   /**
-   * When provided, the textual/code file diff gets line selection: clicking
-   * or dragging over the line numbers selects a range, and a gutter "+"
-   * button appears on the hovered/selected lines. Clicking that button
-   * invokes this callback with the selected range and the button's viewport
-   * rectangle (to anchor a popup to), `null` when it cannot be measured.
+   * Enables line selection and the gutter "+" button; called with the
+   * selected range and the button's viewport rect (`null` when unmeasurable).
    */
   onLineAsk?: (range: SelectedLineRange, anchor: DOMRect | null) => void;
   /**
@@ -321,15 +293,11 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
 
   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<FileDiffMetadata | null>(() => {
     if (!hasContent || imageType !== null) {
       return null;
@@ -342,10 +310,6 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
     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<INotebookDiffResult | null>(() => {
     if (!hasContent || imageType !== null || !isNotebookPath(newName)) {
       return null;
@@ -353,43 +317,31 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
     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?.(notebookDiff !== null);
   }, [onNotebookAvailabilityChange, notebookDiff]);
 
-  // Report the diff shape so hosts can react (e.g. auto-close on empty).
   React.useEffect(() => {
     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?.(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<number>(() =>
     readStoredSplitRatio()
   );
   const wrapperRef = React.useRef<HTMLDivElement | null>(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;
@@ -405,8 +357,6 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
     }
     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 }
     }));
@@ -418,12 +368,8 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
         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);
@@ -469,9 +415,7 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
       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 = wrapperRef.current
         ?.querySelector('diffs-container')
         ?.shadowRoot?.querySelector('[data-gutter-utility-slot]');
@@ -485,8 +429,6 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
 
   const handleResizerPointerDown = React.useCallback(
     (event: React.PointerEvent<HTMLDivElement>) => {
-      // 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;
       }
@@ -519,8 +461,6 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
         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);
@@ -589,9 +529,6 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
     );
   }
   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 (
       <div className="jp-xtralab-DiffWidget-content">
         <ImageDiffView
@@ -611,10 +548,6 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
     );
   }
 
-  // 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}%`
@@ -638,30 +571,16 @@ export function DiffSurface(props: IDiffSurfaceProps): React.ReactElement {
               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,
@@ -698,10 +617,8 @@ export 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}.
+ * 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: {
   mode: NotebookDiffViewMode;
@@ -744,11 +661,9 @@ export function NotebookViewModeControl(props: {
 }
 
 /**
- * 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(): React.ReactElement {
   return (
@@ -781,11 +696,8 @@ function DiffUnifiedIcon(): React.ReactElement {
 }
 
 /**
- * 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: {
   diffStyle: DiffStyle;