xtralab 0.14.1 → 0.15.1

package/lib/git/commands.d.ts

@@ -17,15 +17,24 @@ export declare namespace CommandIDs {
  * Argument shapes used by {@link CommandIDs.openDiff}.
  */
 export declare namespace CommandArguments {
+    /**
+     * The arguments for the open-diff command.
+     */
     interface IOpenDiff {
+        /**
+         * The server-relative path of the repository containing the change.
+         */
         repoPath: string;
+        /**
+         * The file change to show.
+         */
         change: IFileChange;
+        /**
+         * Whether to open the diff as a pinned tab instead of the shared preview.
+         */
         pin?: boolean;
     }
 }
-/**
- * Widget id of the single, reused preview diff tab.
- */
 export declare const PREVIEW_DIFF_WIDGET_ID = "xtralab:diff:preview";
 /**
  * Deterministic widget id for a pinned file/group pair.
@@ -36,18 +45,42 @@ export declare function pinnedDiffWidgetId(change: IFileChange): string;
  */
 export declare class DiffMainAreaWidget extends MainAreaWidget<XtralabDiffWidget> {
     constructor(options: MainAreaWidget.IOptions<XtralabDiffWidget>, change: IFileChange, pinned: boolean, trans: TranslationBundle);
+    /**
+     * The file change currently displayed.
+     */
     get change(): IFileChange;
+    /**
+     * Whether the widget is pinned rather than the shared preview.
+     */
     get pinned(): boolean;
+    /**
+     * Pin the widget; a no-op when already pinned.
+     */
     pin(): void;
+    /**
+     * A signal emitted when the widget becomes pinned.
+     */
     get pinnedChanged(): ISignal<this, boolean>;
+    /**
+     * Display a new file change and update the tab title, caption, and icon.
+     */
     setChange(repoPath: string, change: IFileChange): void;
     private _change;
     private _pinned;
     private _trans;
     private _pinnedChanged;
 }
+/**
+ * The options for {@link registerGitCommands}.
+ */
 interface IRegisterGitCommandsOptions {
+    /**
+     * The JupyterLab application, providing the commands registry and shell.
+     */
     app: JupyterFrontEnd;
+    /**
+     * Theme manager the diff views follow; may be `null`.
+     */
     themeManager: IThemeManager | null;
     /**
      * Contents manager used to write hunk-discard results.
@@ -73,11 +106,13 @@ interface IRegisterGitCommandsOptions {
      * Look up an already-open diff widget for a file change.
      */
     findDiff(change: IFileChange, pin?: boolean): DiffMainAreaWidget | undefined;
+    /**
+     * Callback invoked when a preview diff widget becomes pinned.
+     */
     onPinned(widget: DiffMainAreaWidget): void;
 }
 /**
- * Register the launcher's git diff command on the application command
- * registry.
+ * Register the launcher's git diff command.
  */
 export declare function registerGitCommands(options: IRegisterGitCommandsOptions): void;
 export {};

package/lib/git/commands.js

@@ -11,9 +11,6 @@ export var CommandIDs;
 (function (CommandIDs) {
     CommandIDs.openDiff = 'xtralab:git:open-diff';
 })(CommandIDs || (CommandIDs = {}));
-/**
- * Widget id of the single, reused preview diff tab.
- */
 export const PREVIEW_DIFF_WIDGET_ID = 'xtralab:diff:preview';
 /**
  * Deterministic widget id for a pinned file/group pair.
@@ -38,12 +35,21 @@ export class DiffMainAreaWidget extends MainAreaWidget {
         this._pinned = pinned;
         this._trans = trans;
     }
+    /**
+     * The file change currently displayed.
+     */
     get change() {
         return this._change;
     }
+    /**
+     * Whether the widget is pinned rather than the shared preview.
+     */
     get pinned() {
         return this._pinned;
     }
+    /**
+     * Pin the widget; a no-op when already pinned.
+     */
     pin() {
         if (this._pinned) {
             return;
@@ -51,9 +57,15 @@ export class DiffMainAreaWidget extends MainAreaWidget {
         this._pinned = true;
         this._pinnedChanged.emit(true);
     }
+    /**
+     * A signal emitted when the widget becomes pinned.
+     */
     get pinnedChanged() {
         return this._pinnedChanged;
     }
+    /**
+     * Display a new file change and update the tab title, caption, and icon.
+     */
     setChange(repoPath, change) {
         this._change = change;
         this.content.setModel(fileChangeToDiffModel(repoPath, change));
@@ -62,9 +74,6 @@ export class DiffMainAreaWidget extends MainAreaWidget {
         this.title.icon = getTreeIcon(change.path);
     }
 }
-/**
- * Build the launcher's diff tab around the shared diff widget.
- */
 function createDiffWidget(options) {
     var _a;
     const { repoPath, change, themeManager, contentsManager, rendermime, askAgent, trans } = options;
@@ -89,7 +98,6 @@ function createDiffWidget(options) {
     }
     widget.toolbar.addItem('pin', pinButton);
     addDiffToolbarItems(widget.toolbar, content);
-    // Keep chrome visible only while there is a relevant toolbar control.
     const syncToolbarVisibility = () => {
         if (widget.isDisposed) {
             return;
@@ -115,7 +123,6 @@ function createDiffWidget(options) {
         }
         syncToolbarVisibility();
     };
-    // Auto-close once a discard leaves nothing to show.
     const onEmptied = () => {
         if (!widget.isDisposed) {
             widget.close();
@@ -135,8 +142,7 @@ function createDiffWidget(options) {
     return widget;
 }
 /**
- * Register the launcher's git diff command on the application command
- * registry.
+ * Register the launcher's git diff command.
  */
 export function registerGitCommands(options) {
     const { app, themeManager, contentsManager, rendermime, askAgent, trans, trackDiff, findDiff, onPinned } = options;

package/lib/git/diffModel.js

@@ -40,6 +40,10 @@ function referenceSource(ref) {
 class FileChangeDiffModel {
     constructor(repoPath, change) {
         var _a;
+        /**
+         * A signal emitted when the reference or challenger changes; this static
+         * model never emits it.
+         */
         this.changed = new Signal(this);
         const { oldRef, newRef } = resolveReferences(change);
         // Renames compare the new path against the old path's previous content.

package/lib/git/diffSurface.d.ts

@@ -3,33 +3,28 @@ import { IThemeManager } from '@jupyterlab/apputils';
 import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import type { TranslationBundle } from '@jupyterlab/translation';
 import { type SelectedLineRange } from '@pierre/diffs';
-/**
- * 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 type DiffStyle = 'split' | 'unified';
 /**
- * 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").
+ * Read the persisted diff style, defaulting to `'split'`.
  */
-export type DiffStyle = 'split' | 'unified';
 export declare function readStoredDiffStyle(): DiffStyle;
-export declare 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.
+ * Persist the diff style to local storage (best-effort).
  */
+export declare function writeStoredDiffStyle(style: DiffStyle): void;
 export type NotebookDiffViewMode = 'notebook' | 'json';
+/**
+ * Read the persisted notebook view mode, defaulting to `'notebook'`.
+ */
 export declare function readStoredNotebookViewMode(): NotebookDiffViewMode;
+/**
+ * Persist the notebook view mode to local storage (best-effort).
+ */
 export declare function writeStoredNotebookViewMode(mode: NotebookDiffViewMode): void;
 /**
- * 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 declare function isDarkTheme(themeManager: IThemeManager | null): boolean;
 /**
@@ -37,18 +32,26 @@ export declare function isDarkTheme(themeManager: IThemeManager | null): boolean
  */
 export declare 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.
@@ -71,13 +74,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;
     /**
@@ -89,35 +90,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;
@@ -127,11 +121,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;
     /**
@@ -144,10 +135,8 @@ interface IDiffSurfaceProps {
  */
 export declare 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 declare function NotebookViewModeControl(props: {
     mode: NotebookDiffViewMode;
@@ -156,11 +145,8 @@ export declare function NotebookViewModeControl(props: {
     trans: TranslationBundle;
 }): 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 declare function DiffStyleControl(props: {
     diffStyle: DiffStyle;