xtralab 0.1.0

package/lib/git/commands.js

@@ -0,0 +1,67 @@
+import { refreshIcon } from '@jupyterlab/ui-components';
+import { createGitDiffWidget, diffWidgetId } from './diffWidget';
+/**
+ * Command IDs exposed by the git plugin. Both are registered in
+ * {@link registerGitCommands} so other extensions, the command palette and
+ * keybindings can drive the panel without going through the React internals.
+ */
+export var CommandIDs;
+(function (CommandIDs) {
+    CommandIDs.refresh = 'xtralab:git:refresh';
+    CommandIDs.openDiff = 'xtralab:git:open-diff';
+})(CommandIDs || (CommandIDs = {}));
+/**
+ * Register the git commands on the application command registry. Returns
+ * a disposer that clears the command palette items the registration created
+ * (the commands themselves stay registered for the lifetime of the plugin).
+ */
+export function registerGitCommands(options) {
+    const { app, panel, themeManager, commandPalette, contentsManager, rendermime, onChanged, trackDiff, findDiff } = options;
+    const { commands } = app;
+    commands.addCommand(CommandIDs.refresh, {
+        label: 'Refresh Git Changes',
+        caption: 'Refresh the git changes panel',
+        icon: refreshIcon,
+        execute: () => {
+            panel.refresh();
+        }
+    });
+    commands.addCommand(CommandIDs.openDiff, {
+        label: 'Open Git Diff',
+        caption: 'Open a side-by-side diff for a changed file',
+        execute: async (args) => {
+            const typed = args;
+            if ((typed === null || typed === void 0 ? void 0 : typed.change) === undefined) {
+                return;
+            }
+            const existing = findDiff(typed.change);
+            if (existing !== undefined && !existing.isDisposed) {
+                app.shell.activateById(existing.id);
+                return;
+            }
+            const widget = createGitDiffWidget({
+                repoPath: typed.repoPath,
+                change: typed.change,
+                themeManager,
+                contentsManager,
+                rendermime,
+                onChanged
+            });
+            await trackDiff(widget);
+            app.shell.add(widget, 'main', { mode: 'tab-after' });
+            app.shell.activateById(widget.id);
+        }
+    });
+    const paletteItems = commandPalette
+        ? [
+            commandPalette.addItem({
+                command: CommandIDs.refresh,
+                category: 'Git'
+            })
+        ]
+        : [];
+    return () => {
+        paletteItems.forEach(item => item.dispose());
+    };
+}
+export { diffWidgetId };

package/lib/git/diffWidget.d.ts

@@ -0,0 +1,108 @@
+import * as React from 'react';
+import { IThemeManager, MainAreaWidget } from '@jupyterlab/apputils';
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import { Contents } from '@jupyterlab/services';
+import { ReactWidget } from '@jupyterlab/ui-components';
+import { ISignal } from '@lumino/signaling';
+import { GitReference, IFileChange } from './tokens';
+/**
+ * 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";
+/**
+ * View modes available for `.ipynb` diffs. `notebook` is the cell-by-cell
+ * rendered view; `json` falls back to the raw nbformat JSON file diff so
+ * the user can inspect exactly which bytes changed (handy for nbformat
+ * spelunking, seeing execution_count drift, etc.).
+ */
+type NotebookDiffViewMode = 'notebook' | 'json';
+/**
+ * Build the deterministic widget id used for a diff against a particular
+ * file/group pair. Reused across plugin and command code so reopening a
+ * diff for the same file reveals the existing tab instead of opening a
+ * second one.
+ */
+export declare function diffWidgetId(change: IFileChange): string;
+/**
+ * Resolve the pair of git references whose `content` should appear on the
+ * left and right side of the diff for a given file change. Mirrors VS
+ * Code's source control diff: staged-side compares INDEX vs HEAD,
+ * unstaged-side compares WORKING vs INDEX, and untracked files have no
+ * "previous" version to compare against.
+ */
+export declare function resolveReferences(change: IFileChange): {
+    oldRef: GitReference | null;
+    newRef: GitReference | null;
+};
+export interface IGitDiffWidgetOptions {
+    repoPath: string;
+    change: IFileChange;
+    themeManager: IThemeManager | null;
+    contentsManager: Contents.IManager;
+    /**
+     * Rendermime registry used by the notebook diff path 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.
+     */
+    rendermime: IRenderMimeRegistry | null;
+    /**
+     * Called after a hunk-level operation mutates the working tree, so the
+     * surrounding plugin can refresh the changes panel.
+     */
+    onChanged: () => void;
+    /**
+     * Called when a post-discard reload finds no hunks left in the diff.
+     * Wired by {@link createGitDiffWidget} to close the host
+     * `MainAreaWidget` — there is nothing left to view, so the empty pane
+     * would just be visual noise.
+     */
+    onEmpty?: () => void;
+}
+/**
+ * Build a `MainAreaWidget`-hosted diff viewer for a single file change.
+ * Wrapping the `ReactWidget` in a `MainAreaWidget` is what gives it the
+ * usual document chrome — toolbar slot, focus tracker integration, and
+ * spinner-while-loading hooks — and matches the pattern used for other
+ * read-only main-area widgets in the JupyterLab ecosystem.
+ */
+export declare function createGitDiffWidget(options: IGitDiffWidgetOptions): MainAreaWidget<DiffContentWidget>;
+/**
+ * The actual React-rendered region of the diff viewer. Held in its own
+ * `ReactWidget` so the surrounding `MainAreaWidget` can manage chrome
+ * without React having to know about it.
+ *
+ * Owns the persistent UI state that the surrounding `MainAreaWidget`
+ * toolbar needs to read and write (`notebookViewMode` and whether a
+ * notebook view is even available for the current file). Storing this on
+ * the widget — and exposing change signals — lets the toolbar widget and
+ * the React content stay in sync without either side knowing about the
+ * other.
+ */
+export declare class DiffContentWidget extends ReactWidget {
+    constructor(options: IGitDiffWidgetOptions);
+    /** The change this widget renders, used by callers to identify the widget. */
+    get change(): IFileChange;
+    /** The user's current rendered-vs-JSON view choice for notebook diffs. */
+    get notebookViewMode(): NotebookDiffViewMode;
+    /** Update the notebook view mode and persist it across sessions. */
+    setNotebookViewMode(mode: NotebookDiffViewMode): void;
+    /** Emits whenever {@link notebookViewMode} changes. */
+    get notebookViewModeChanged(): ISignal<this, NotebookDiffViewMode>;
+    /**
+     * Whether a rendered notebook view is currently available. Set by the
+     * React content once it has parsed the diff; the toolbar reads this to
+     * decide whether to show the view-mode selector.
+     */
+    get hasNotebookView(): boolean;
+    setHasNotebookView(value: boolean): void;
+    /** Emits whenever {@link hasNotebookView} changes. */
+    get hasNotebookViewChanged(): ISignal<this, boolean>;
+    protected render(): React.ReactElement;
+    private _options;
+    private _notebookViewMode;
+    private _notebookViewModeChanged;
+    private _hasNotebookView;
+    private _hasNotebookViewChanged;
+}
+export {};