xtralab 0.15.0 → 0.15.2

package/lib/git/index.js

@@ -1,25 +1,60 @@
 import { IThemeManager, WidgetTracker } from '@jupyterlab/apputils';
 import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { IStateDB } from '@jupyterlab/statedb';
 import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 import { IAskAgent } from '../askAgent/tokens';
 import { CommandIDs, PREVIEW_DIFF_WIDGET_ID, pinnedDiffWidgetId, registerGitCommands } from './commands';
+import { DiffPreferences, IDiffPreferences } from './diffPreferences';
 import diffProviderPlugin from './diffProvider';
 const GIT_DIFF_COMMAND_PLUGIN_ID = 'xtralab:git-diff-command';
+const GIT_DIFF_PREFERENCES_PLUGIN_ID = 'xtralab:git-diff-preferences';
 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 display choices shared by the launcher diff and the Git panel diff.
+ */
+const diffPreferencesPlugin = {
+    id: GIT_DIFF_PREFERENCES_PLUGIN_ID,
+    description: 'Keeps the git diff display choices in the settings and the state database.',
+    autoStart: true,
+    provides: IDiffPreferences,
+    optional: [ISettingRegistry, IStateDB],
+    activate: (app, settingRegistry, state) => {
+        const preferences = new DiffPreferences();
+        if (settingRegistry !== null) {
+            settingRegistry
+                .load(GIT_DIFF_PREFERENCES_PLUGIN_ID)
+                .then(settings => preferences.connectSettings(settings))
+                .catch(reason => {
+                console.error(`xtralab: failed to load settings for ${GIT_DIFF_PREFERENCES_PLUGIN_ID}`, reason);
+            });
+        }
+        if (state !== null) {
+            preferences.connectState(state).catch(reason => {
+                console.error('xtralab: failed to restore the diff split', reason);
+            });
+        }
+        return preferences;
+    }
+};
+/**
+ * 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,
     description: "The launcher dashboard's side-by-side git diff command, powered by @pierre/diffs.",
     autoStart: true,
-    optional: [IThemeManager, IRenderMimeRegistry, ITranslator, IAskAgent],
-    activate: (app, themeManager, rendermime, translator, askAgent) => {
+    optional: [
+        IThemeManager,
+        IRenderMimeRegistry,
+        ITranslator,
+        IAskAgent,
+        IDiffPreferences
+    ],
+    activate: (app, themeManager, rendermime, translator, askAgent, preferences) => {
         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
         });
@@ -34,6 +69,7 @@ const diffCommandPlugin = {
             contentsManager: app.serviceManager.contents,
             rendermime,
             askAgent,
+            preferences: preferences !== null && preferences !== void 0 ? preferences : new DiffPreferences(),
             trans,
             trackDiff: widget => tracker.add(widget),
             onPinned: current => {
@@ -53,10 +89,8 @@ const diffCommandPlugin = {
         });
     }
 };
-/**
- * Plugins contributed by xtralab's git integration.
- */
 const plugins = [
+    diffPreferencesPlugin,
     diffCommandPlugin,
     diffProviderPlugin
 ];

package/lib/git/notebookDiff.d.ts

@@ -3,42 +3,103 @@ import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import type { TranslationBundle } from '@jupyterlab/translation';
 import { type FileDiffMetadata } from '@pierre/diffs';
 /**
- * Minimal slice of nbformat 4.x that the diff inspects. Fields we don't
- * read (attachments, e.g.) are intentionally not narrowed — we still pass
- * them around as part of the cell, but we never project them into the diff.
+ * Minimal slice of nbformat 4.x that the diff inspects.
  */
 interface INotebookCell {
+    /**
+     * The cell type ('code', 'markdown', or 'raw').
+     */
     cell_type: string;
+    /**
+     * Stable cell id (nbformat >= 4.5); absent in older notebooks.
+     */
     id?: string;
+    /**
+     * The cell source, as a single string or an array of lines.
+     */
     source: string | string[];
+    /**
+     * Execution outputs; present on code cells only.
+     */
     outputs?: INotebookOutput[];
+    /**
+     * The cell-level metadata.
+     */
     metadata?: Record<string, unknown>;
+    /**
+     * Execution count of a code cell; `null` when the cell has not run.
+     */
     execution_count?: number | null;
+    /**
+     * Media attachments keyed by name (markdown and raw cells).
+     */
     attachments?: Record<string, unknown>;
 }
+/**
+ * Minimal slice of an nbformat 4.x cell output that the diff inspects.
+ */
 interface INotebookOutput {
+    /**
+     * The output type ('stream', 'execute_result', 'display_data', or 'error').
+     */
     output_type: string;
+    /**
+     * The mime bundle of an `execute_result` or `display_data` output.
+     */
     data?: Record<string, unknown>;
+    /**
+     * The text of a `stream` output.
+     */
     text?: string | string[];
+    /**
+     * The stream name ('stdout' or 'stderr') of a `stream` output.
+     */
     name?: string;
+    /**
+     * The exception name of an `error` output.
+     */
     ename?: string;
+    /**
+     * The exception message of an `error` output.
+     */
     evalue?: string;
+    /**
+     * The traceback lines of an `error` output; may contain ANSI escapes.
+     */
     traceback?: string[];
+    /**
+     * The execution count of an `execute_result` output.
+     */
     execution_count?: number | null;
+    /**
+     * The output-level metadata.
+     */
     metadata?: Record<string, unknown>;
 }
+/**
+ * Minimal slice of an nbformat 4.x notebook that the diff inspects.
+ */
 interface INotebook {
+    /**
+     * The notebook cells.
+     */
     cells: INotebookCell[];
+    /**
+     * The notebook-level metadata.
+     */
     metadata: Record<string, unknown>;
+    /**
+     * The nbformat major version.
+     */
     nbformat: number;
+    /**
+     * The nbformat minor version.
+     */
     nbformat_minor: number;
 }
 /**
- * One entry in the per-cell diff. `unchanged` cells are rendered as a
- * collapsed summary; the other variants render their source / outputs /
- * metadata via {@link FileDiff}. The `modified` and `unchanged` branches
- * carry the same payload but live on separate union members so `Extract`
- * narrowing works on `kind` literals downstream.
+ * One entry in the per-cell diff. `modified` and `unchanged` carry the same
+ * payload on separate union members so `Extract` narrowing on `kind` works.
  */
 type NotebookCellDiff = {
     kind: 'modified';
@@ -62,48 +123,69 @@ type NotebookCellDiff = {
     oldIndex: number;
 };
 /**
- * Notebook-level diff result returned by {@link buildNotebookDiff}. Returns
- * `null` from the builder when either side fails to parse — the caller then
- * falls back to a raw JSON file diff.
+ * Notebook-level diff result returned by {@link buildNotebookDiff}.
  */
 export interface INotebookDiffResult {
+    /**
+     * The parsed old revision of the notebook.
+     */
     oldNotebook: INotebook;
+    /**
+     * The parsed new revision of the notebook.
+     */
     newNotebook: INotebook;
+    /**
+     * Per-cell diff entries, in new-notebook order with removed cells appended.
+     */
     cells: NotebookCellDiff[];
     /**
-     * Kernel language pulled from `metadata.language_info.name`, used to pick
-     * a syntax-highlighting filename for code cells.
+     * Kernel language from `metadata.language_info.name`; picks the highlighting filename.
      */
     language: string | undefined;
     /**
-     * Pre-computed diff for notebook-level metadata (kernelspec, language_info,
-     * nbformat) when it differs between revisions; `null` otherwise so the
-     * section can be hidden without further checks.
+     * Diff of notebook-level metadata when it differs between revisions; `null` otherwise.
      */
     notebookMetadataDiff: FileDiffMetadata | null;
 }
+/**
+ * Options for {@link buildNotebookDiff}.
+ */
 interface IBuildNotebookDiffOptions {
+    /**
+     * The raw text of the old notebook revision.
+     */
     oldText: string;
+    /**
+     * The raw text of the new notebook revision.
+     */
     newText: string;
 }
 /**
- * Build a complete notebook diff from the textual contents of two
- * revisions. Returns `null` if either side fails to parse as a notebook;
- * the caller is expected to fall back to a raw text diff in that case.
- *
- * An empty string on either side is treated as an empty notebook (no
- * cells, default metadata) so a freshly-added or deleted notebook still
- * produces a sensible cell-by-cell diff.
+ * Build a notebook diff from the text of two revisions. Returns `null` when
+ * either side fails to parse (caller falls back to a raw text diff); an
+ * empty string counts as an empty notebook so added/deleted notebooks still
+ * diff cell by cell.
  */
 export declare function buildNotebookDiff(options: IBuildNotebookDiffOptions): INotebookDiffResult | null;
+/**
+ * Props for {@link NotebookDiffView}.
+ */
 interface INotebookDiffViewProps {
+    /**
+     * The notebook diff to render.
+     */
     diff: INotebookDiffResult;
+    /**
+     * Whether the active JupyterLab theme is dark.
+     */
     dark: boolean;
     /**
-     * Whether a Pierre JupyterLab theme is active; selects Pierre's rich
-     * highlighting vs the CSS-variable theme (see {@link resolveDiffTheme}).
+     * Whether a Pierre JupyterLab theme is active; selects Pierre highlighting vs the CSS-variable theme.
      */
     pierreTheme: boolean;
+    /**
+     * Registry rendering markdown and output previews; `null` falls back to plain text.
+     */
     rendermime: IRenderMimeRegistry | null;
     /**
      * Translation bundle for user-facing strings.
@@ -111,14 +193,9 @@ interface INotebookDiffViewProps {
     trans: TranslationBundle;
 }
 /**
- * The notebook-level diff view. Lays out cells in a 2-column grid where
- * the left column tracks the *old* notebook and the right column tracks
- * the *new* one — modified and unchanged cells span both columns (their
- * internal split-mode FileDiff aligns with the outer columns), added
- * cells live in the right column with an empty placeholder on the left,
- * and removed cells live in the left column with an empty placeholder on
- * the right. The diff library's red/green tint within each cell makes
- * the orientation clear without a separate column header.
+ * Notebook-level diff view: a 2-column grid where the left column tracks
+ * the old notebook and the right the new one — modified/unchanged cells
+ * span both, added cells sit right, removed cells sit left.
  */
 export declare function NotebookDiffView(props: INotebookDiffViewProps): React.ReactElement;
 export {};