xtralab 0.4.0 → 0.5.0

package/src/git/imageDiff.tsx

@@ -0,0 +1,368 @@
+import * as React from 'react';
+
+/**
+ * xtralab's image diff, registered in place of `@jupyterlab/git:image-diff`.
+ *
+ * The git server base64-encodes binary content, so both diff hosts receive
+ * the two sides as base64 strings through the same `content()` getters used
+ * for text. This module turns those strings into `<img>` elements and
+ * offers the 2-up / swipe / onion-skin comparison modes; no diffing library
+ * is involved (`@pierre/diffs` is text-only).
+ */
+
+/**
+ * Raster image extensions xtralab renders as an image diff, mapped to the
+ * MIME subtype used in the `data:image/<subtype>;base64,…` URL.
+ *
+ * `.svg` is intentionally absent: it is XML text, so the `@pierre/diffs`
+ * text diff (the fallback provider) is more useful for it than an image
+ * comparison.
+ */
+const IMAGE_DATA_TYPES: Record<string, string> = {
+  '.png': 'png',
+  '.jpg': 'jpeg',
+  '.jpeg': 'jpeg',
+  '.gif': 'gif',
+  '.webp': 'webp',
+  '.bmp': 'bmp',
+  '.ico': 'x-icon'
+};
+
+/** The file extensions registered as the xtralab image diff provider. */
+export const IMAGE_DIFF_EXTENSIONS = Object.keys(IMAGE_DATA_TYPES);
+
+/**
+ * The `data:` MIME subtype for a path xtralab renders as an image, or
+ * `null` when the path is not a supported raster image.
+ */
+export function imageDataType(path: string): string | null {
+  const lower = path.toLowerCase();
+  const dot = lower.lastIndexOf('.');
+  if (dot < 0) {
+    return null;
+  }
+  return IMAGE_DATA_TYPES[lower.slice(dot)] ?? null;
+}
+
+/** Comparison layouts, matching jupyterlab-git's image diff modes. */
+type ImageDiffViewMode = '2-up' | 'swipe' | 'onion';
+
+const IMAGE_DIFF_VIEW_MODE_STORAGE_KEY = 'xtralab:image-diff-view-mode';
+
+function readStoredImageViewMode(): ImageDiffViewMode {
+  try {
+    const raw = window.localStorage.getItem(IMAGE_DIFF_VIEW_MODE_STORAGE_KEY);
+    if (raw === '2-up' || raw === 'swipe' || raw === 'onion') {
+      return raw;
+    }
+  } catch {
+    // localStorage can throw in privacy/sandboxed contexts — 2-up is the
+    // sensible default anyway.
+  }
+  return '2-up';
+}
+
+function writeStoredImageViewMode(mode: ImageDiffViewMode): void {
+  try {
+    window.localStorage.setItem(IMAGE_DIFF_VIEW_MODE_STORAGE_KEY, mode);
+  } catch {
+    // Best-effort.
+  }
+}
+
+/**
+ * Strip whitespace from a base64 payload. Python's `base64.encodebytes`
+ * (used by the git server) inserts a newline every 76 characters; most
+ * browsers tolerate that inside a `data:` URL but some are stricter, and
+ * the cleaned length also lets us size the file accurately.
+ */
+function cleanBase64(value: string): string {
+  return value.replace(/\s+/g, '');
+}
+
+/** Decoded byte length of a (whitespace-free) base64 string. */
+function base64ByteLength(clean: string): number {
+  if (clean.length === 0) {
+    return 0;
+  }
+  const padding = clean.endsWith('==') ? 2 : clean.endsWith('=') ? 1 : 0;
+  return Math.floor((clean.length * 3) / 4) - padding;
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  const units = ['KB', 'MB', 'GB'];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value.toFixed(value < 10 ? 1 : 0)} ${units[unit]}`;
+}
+
+interface IImageSide {
+  /** Cleaned base64 payload; empty string means the side does not exist. */
+  data: string;
+  present: boolean;
+  uri: string | null;
+  bytes: number;
+}
+
+function toSide(raw: string, fileType: string): IImageSide {
+  const data = cleanBase64(raw);
+  const present = data.length > 0;
+  return {
+    data,
+    present,
+    uri: present ? `data:image/${fileType};base64,${data}` : null,
+    bytes: base64ByteLength(data)
+  };
+}
+
+interface IImageDiffViewProps {
+  /** Base64 of the reference (old) revision; empty when added. */
+  reference: string;
+  /** Base64 of the challenger (new) revision; empty when deleted. */
+  challenger: string;
+  /** MIME subtype from {@link imageDataType}. */
+  fileType: string;
+}
+
+/**
+ * The image comparison surface: a segmented mode selector (reusing the
+ * diff segmented-control styling so it matches the Notebook/JSON toggle)
+ * plus the selected 2-up / swipe / onion-skin view.
+ */
+export function ImageDiffView(props: IImageDiffViewProps): React.ReactElement {
+  const { reference, challenger, fileType } = props;
+  const ref = React.useMemo(
+    () => toSide(reference, fileType),
+    [reference, fileType]
+  );
+  const chall = React.useMemo(
+    () => toSide(challenger, fileType),
+    [challenger, fileType]
+  );
+
+  const [mode, setMode] = React.useState<ImageDiffViewMode>(() =>
+    readStoredImageViewMode()
+  );
+  const changeMode = React.useCallback((next: ImageDiffViewMode) => {
+    setMode(next);
+    writeStoredImageViewMode(next);
+  }, []);
+
+  return (
+    <div className="jp-xtralab-ImageDiff">
+      <div className="jp-xtralab-ImageDiff-header">
+        <div
+          className="jp-xtralab-DiffWidget-segmented"
+          role="tablist"
+          aria-label="Image diff view mode"
+        >
+          {(
+            [
+              ['2-up', '2-up'],
+              ['swipe', 'Swipe'],
+              ['onion', 'Onion Skin']
+            ] as [ImageDiffViewMode, string][]
+          ).map(([value, label]) => (
+            <button
+              key={value}
+              type="button"
+              role="tab"
+              aria-selected={mode === value}
+              data-active={mode === value}
+              className="jp-xtralab-DiffWidget-segmentedButton"
+              onClick={() => changeMode(value)}
+            >
+              {label}
+            </button>
+          ))}
+        </div>
+      </div>
+      <div className="jp-xtralab-ImageDiff-body">
+        {mode === '2-up' ? (
+          <TwoUp reference={ref} challenger={chall} />
+        ) : mode === 'swipe' ? (
+          <Swipe reference={ref} challenger={chall} />
+        ) : (
+          <OnionSkin reference={ref} challenger={chall} />
+        )}
+      </div>
+    </div>
+  );
+}
+
+interface ISideViewProps {
+  reference: IImageSide;
+  challenger: IImageSide;
+}
+
+function useNaturalSize(): [
+  [number, number] | null,
+  (event: React.SyntheticEvent<HTMLImageElement>) => void
+] {
+  const [size, setSize] = React.useState<[number, number] | null>(null);
+  const onLoad = React.useCallback(
+    (event: React.SyntheticEvent<HTMLImageElement>) => {
+      setSize([
+        event.currentTarget.naturalWidth,
+        event.currentTarget.naturalHeight
+      ]);
+    },
+    []
+  );
+  return [size, onLoad];
+}
+
+function caption(
+  side: IImageSide,
+  size: [number, number] | null,
+  emptyLabel: string
+): string {
+  if (!side.present) {
+    return emptyLabel;
+  }
+  const dims = size !== null ? `${size[0]}×${size[1]} · ` : '';
+  return `${dims}${formatBytes(side.bytes)}`;
+}
+
+function TwoUp({ reference, challenger }: ISideViewProps): React.ReactElement {
+  const [refSize, onRefLoad] = useNaturalSize();
+  const [challSize, onChallLoad] = useNaturalSize();
+  return (
+    <div className="jp-xtralab-ImageDiff-twoUp">
+      <figure className="jp-xtralab-ImageDiff-col">
+        <div className="jp-xtralab-ImageDiff-frame" data-side="reference">
+          {reference.uri !== null ? (
+            <img
+              className="jp-xtralab-ImageDiff-img"
+              src={reference.uri}
+              alt="Reference revision"
+              onLoad={onRefLoad}
+            />
+          ) : (
+            <div className="jp-xtralab-ImageDiff-empty">No previous image</div>
+          )}
+        </div>
+        <figcaption className="jp-xtralab-ImageDiff-caption">
+          {caption(reference, refSize, 'Added')}
+        </figcaption>
+      </figure>
+      <figure className="jp-xtralab-ImageDiff-col">
+        <div className="jp-xtralab-ImageDiff-frame" data-side="challenger">
+          {challenger.uri !== null ? (
+            <img
+              className="jp-xtralab-ImageDiff-img"
+              src={challenger.uri}
+              alt="Challenger revision"
+              onLoad={onChallLoad}
+            />
+          ) : (
+            <div className="jp-xtralab-ImageDiff-empty">Deleted</div>
+          )}
+        </div>
+        <figcaption className="jp-xtralab-ImageDiff-caption">
+          {caption(challenger, challSize, 'Deleted')}
+        </figcaption>
+      </figure>
+    </div>
+  );
+}
+
+/**
+ * Range slider shared by the swipe and onion-skin views. A native
+ * `<input type="range">` (styled via CSS) keeps the bundle free of a UI
+ * component dependency.
+ */
+function RangeSlider(props: {
+  value: number;
+  onChange: (value: number) => void;
+  ariaLabel: string;
+}): React.ReactElement {
+  const { value, onChange, ariaLabel } = props;
+  return (
+    <input
+      className="jp-xtralab-ImageDiff-slider"
+      type="range"
+      min={0}
+      max={100}
+      step={1}
+      value={value}
+      aria-label={ariaLabel}
+      onChange={event => onChange(Number(event.target.value))}
+    />
+  );
+}
+
+function Swipe({ reference, challenger }: ISideViewProps): React.ReactElement {
+  const [position, setPosition] = React.useState(50);
+  return (
+    <div className="jp-xtralab-ImageDiff-interactive">
+      <div className="jp-xtralab-ImageDiff-stack">
+        {reference.uri !== null ? (
+          <img
+            className="jp-xtralab-ImageDiff-stackImg"
+            src={reference.uri}
+            alt="Reference revision"
+            style={{
+              clipPath: `inset(0 ${100 - position}% 0 0)`
+            }}
+          />
+        ) : null}
+        {challenger.uri !== null ? (
+          <img
+            className="jp-xtralab-ImageDiff-stackImg"
+            src={challenger.uri}
+            alt="Challenger revision"
+            style={{
+              clipPath: `inset(0 0 0 ${position}%)`
+            }}
+          />
+        ) : null}
+      </div>
+      <RangeSlider
+        value={position}
+        onChange={setPosition}
+        ariaLabel="Swipe between reference and challenger"
+      />
+    </div>
+  );
+}
+
+function OnionSkin({
+  reference,
+  challenger
+}: ISideViewProps): React.ReactElement {
+  const [opacity, setOpacity] = React.useState(50);
+  return (
+    <div className="jp-xtralab-ImageDiff-interactive">
+      <div className="jp-xtralab-ImageDiff-stack">
+        {reference.uri !== null ? (
+          <img
+            className="jp-xtralab-ImageDiff-stackImg"
+            src={reference.uri}
+            alt="Reference revision"
+          />
+        ) : null}
+        {challenger.uri !== null ? (
+          <img
+            className="jp-xtralab-ImageDiff-stackImg"
+            src={challenger.uri}
+            alt="Challenger revision"
+            style={{ opacity: opacity / 100 }}
+          />
+        ) : null}
+      </div>
+      <RangeSlider
+        value={opacity}
+        onChange={setOpacity}
+        ariaLabel="Fade between reference and challenger"
+      />
+    </div>
+  );
+}

package/src/git/index.ts

@@ -1,66 +1,47 @@
 import {
-  ILayoutRestorer,
   JupyterFrontEnd,
   JupyterFrontEndPlugin
 } from '@jupyterlab/application';
-import {
-  Dialog,
-  ICommandPalette,
-  IThemeManager,
-  WidgetTracker,
-  showDialog,
-  showErrorMessage
-} from '@jupyterlab/apputils';
+import { IThemeManager, WidgetTracker } from '@jupyterlab/apputils';
 import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 
-import { ReadonlyPartialJSONObject } from '@lumino/coreutils';
-
 import { CommandArguments, CommandIDs, registerGitCommands } from './commands';
 import {
   DiffContentWidget,
   PREVIEW_DIFF_WIDGET_ID,
   pinnedDiffWidgetId
 } from './diffWidget';
+import diffProviderPlugin from './diffProvider';
 import type { MainAreaWidget } from '@jupyterlab/apputils';
-import { GitPanel } from './panel';
 import { IFileChange } from './tokens';
 
-const GIT_PLUGIN_ID = 'xtralab:git';
+const GIT_DIFF_COMMAND_PLUGIN_ID = 'xtralab:git-diff-command';
 const GIT_DIFF_TRACKER_NAMESPACE = 'xtralab-git-diff';
 
 /**
- * The git plugin. Adds a VS Code-style "Source Control" panel to the
- * JupyterLab left sidebar and opens file diffs in the main area when the
- * user clicks an entry in the panel. Backed by the `jupyterlab_git` server
- * extension's REST API; the bundled `@jupyterlab/git` frontend is disabled
- * via `package.json`'s `jupyterlab.disabledExtensions` so the two panels do
- * not coexist.
+ * The launcher's git diff command plugin.
+ *
+ * The `@jupyterlab/git` frontend stays enabled (only its diff plugins are
+ * swapped — see `diffProvider.tsx`), so the upstream git panel is what the
+ * user sees in the sidebar. This plugin is the launcher dashboard's
+ * independent diff path: the `xtralab:git:open-diff` command the
+ * dashboard's "Changes" section calls, plus a tracker so reopening a diff
+ * reveals the existing tab and the preview/pin behavior keeps working.
  */
-const plugin: JupyterFrontEndPlugin<void> = {
-  id: GIT_PLUGIN_ID,
+const diffCommandPlugin: JupyterFrontEndPlugin<void> = {
+  id: GIT_DIFF_COMMAND_PLUGIN_ID,
   description:
-    'A VS Code-style git changes panel and diff viewer powered by jupyterlab-git and @pierre/diffs.',
+    "The launcher dashboard's side-by-side git diff command, powered by @pierre/diffs.",
   autoStart: true,
-  optional: [
-    ILayoutRestorer,
-    IThemeManager,
-    ICommandPalette,
-    IRenderMimeRegistry
-  ],
+  optional: [IThemeManager, IRenderMimeRegistry],
   activate: (
     app: JupyterFrontEnd,
-    restorer: ILayoutRestorer | null,
     themeManager: IThemeManager | null,
-    commandPalette: ICommandPalette | null,
     rendermime: IRenderMimeRegistry | null
   ): void => {
-    // Match the panel's repo path: empty string means "use the JupyterLab
-    // server's root and let git resolve the enclosing repo".
-    const repoPath = '';
-
-    // Track open diff widgets so the layout restorer can recreate them on
-    // reload, and so the openDiff handler can reveal an already-open diff
-    // for the same file instead of creating a duplicate.
+    // Track open diff widgets so the openDiff handler can reveal an
+    // already-open diff for the same file instead of creating a duplicate
+    // (and so a promoted preview can find its pinned twin).
     const tracker = new WidgetTracker<MainAreaWidget<DiffContentWidget>>({
       namespace: GIT_DIFF_TRACKER_NAMESPACE
     });
@@ -76,41 +57,15 @@ const plugin: JupyterFrontEndPlugin<void> = {
       return existing ?? undefined;
     };
 
-    const panel = new GitPanel({
-      openDiff: (change, options) => {
-        const args: CommandArguments.IOpenDiff = { repoPath, change };
-        if (options?.pin === true) {
-          args.pin = true;
-        }
-        void app.commands.execute(
-          CommandIDs.openDiff,
-          args as unknown as ReadonlyPartialJSONObject
-        );
-      },
-      confirm: async (title, body, accept) => {
-        const result = await showDialog({
-          title,
-          body,
-          buttons: [Dialog.cancelButton(), Dialog.warnButton({ label: accept })]
-        });
-        return result.button.accept === true;
-      },
-      showError: showErrorMessage
-    });
-
-    app.shell.add(panel, 'left', { rank: 60 });
-    if (restorer !== null) {
-      restorer.add(panel, panel.id);
-    }
-
     registerGitCommands({
       app,
-      panel,
       themeManager,
-      commandPalette,
       contentsManager: app.serviceManager.contents,
       rendermime,
-      onChanged: () => panel.refresh(),
+      // The launcher polls git status on its own cadence and the
+      // jupyterlab-git panel auto-refreshes on the contents `fileChanged`
+      // signal a hunk-discard save emits, so no extra refresh is needed.
+      onChanged: () => undefined,
       trackDiff: widget => tracker.add(widget),
       onPinned: current => {
         const existing = findDiff(current.content.change, true);
@@ -132,4 +87,19 @@ const plugin: JupyterFrontEndPlugin<void> = {
   }
 };
 
-export default plugin;
+/**
+ * Every plugin contributed by xtralab's git integration:
+ *
+ *   1. {@link diffCommandPlugin} — the launcher's `xtralab:git:open-diff`.
+ *   2. `diffProviderPlugin` — registers the `@pierre/diffs` rendering as
+ *      jupyterlab-git's diff providers (replacing its disabled
+ *      notebook/text diff plugins).
+ */
+const plugins: JupyterFrontEndPlugin<unknown>[] = [
+  diffCommandPlugin,
+  diffProviderPlugin
+];
+
+export { CommandArguments, CommandIDs };
+
+export default plugins;

package/src/index.ts

@@ -3,7 +3,7 @@ import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 import fileBrowserPlugin from './fileBrowser';
 import editorBreadcrumbsPlugin from './editorBreadcrumbs';
 import editorIndentPlugin from './editorIndent';
-import gitPlugin from './git';
+import gitPlugins from './git';
 import launcherPlugin from './launcher';
 import menusPlugin from './menus';
 import sidebarPlugin from './sidebar';
@@ -12,15 +12,16 @@ import statusBarPlugin from './statusBar';
 /**
  * Every plugin contributed by `xtralab`. The entry point of the
  * labextension is an array because the package bundles several independent
- * enhancements (file browser, git changes panel, …) — JupyterLab activates
+ * enhancements (file browser, git diff providers, …) — JupyterLab activates
  * each plugin individually and only the ones whose required tokens are
- * available end up running.
+ * available end up running. `gitPlugins` is itself an array (the launcher
+ * diff command + the jupyterlab-git diff providers), so it is spread in.
  */
 const plugins: JupyterFrontEndPlugin<unknown>[] = [
   editorBreadcrumbsPlugin,
   editorIndentPlugin,
   fileBrowserPlugin,
-  gitPlugin,
+  ...gitPlugins,
   launcherPlugin,
   menusPlugin,
   sidebarPlugin,