xtralab 0.15.0 → 0.15.1

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 {};