xtralab 0.1.0

package/lib/git/panel.d.ts

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import { ReactWidget } from '@jupyterlab/ui-components';
+import { ISignal } from '@lumino/signaling';
+import { IGitPanelHandlers } from './panelComponent';
+/**
+ * The id and CSS class used for the git panel widget. The id ends up as the
+ * sidebar tab id (so layout restoration can find the widget) and the CSS
+ * class lets per-panel styles attach without leaking to other widgets.
+ */
+export declare const GIT_PANEL_ID = "xtralab:git-panel";
+export declare const GIT_PANEL_CSS_CLASS = "jp-xtralab-GitPanel";
+/**
+ * The lumino host widget for the git changes panel. Owns the `refresh`
+ * signal that the React component listens to, and exposes a typed callback
+ * surface (`handlers`) the React component uses to react to user actions.
+ */
+export declare class GitPanel extends ReactWidget {
+    constructor(handlers: IGitPanelHandlers);
+    /**
+     * Public refresh hook called by the plugin when something happened that
+     * invalidates the current view (the user clicked the toolbar refresh, the
+     * file browser refreshed, a focused notebook saved, …).
+     */
+    refresh(): void;
+    get refreshRequested(): ISignal<this, void>;
+    protected render(): React.ReactElement;
+    private _handlers;
+    private _refreshRequested;
+}

package/lib/git/panel.js

@@ -0,0 +1,42 @@
+import * as React from 'react';
+import { ReactWidget } from '@jupyterlab/ui-components';
+import { Signal } from '@lumino/signaling';
+import { gitIcon } from './icons';
+import { GitPanelComponent } from './panelComponent';
+/**
+ * The id and CSS class used for the git panel widget. The id ends up as the
+ * sidebar tab id (so layout restoration can find the widget) and the CSS
+ * class lets per-panel styles attach without leaking to other widgets.
+ */
+export const GIT_PANEL_ID = 'xtralab:git-panel';
+export const GIT_PANEL_CSS_CLASS = 'jp-xtralab-GitPanel';
+/**
+ * The lumino host widget for the git changes panel. Owns the `refresh`
+ * signal that the React component listens to, and exposes a typed callback
+ * surface (`handlers`) the React component uses to react to user actions.
+ */
+export class GitPanel extends ReactWidget {
+    constructor(handlers) {
+        super();
+        this._refreshRequested = new Signal(this);
+        this.id = GIT_PANEL_ID;
+        this.title.icon = gitIcon;
+        this.title.caption = 'Git Changes';
+        this.addClass(GIT_PANEL_CSS_CLASS);
+        this._handlers = handlers;
+    }
+    /**
+     * Public refresh hook called by the plugin when something happened that
+     * invalidates the current view (the user clicked the toolbar refresh, the
+     * file browser refreshed, a focused notebook saved, …).
+     */
+    refresh() {
+        this._refreshRequested.emit();
+    }
+    get refreshRequested() {
+        return this._refreshRequested;
+    }
+    render() {
+        return (React.createElement(GitPanelComponent, { handlers: this._handlers, refreshSignal: this._refreshRequested }));
+    }
+}

package/lib/git/panelComponent.d.ts

@@ -0,0 +1,26 @@
+import * as React from 'react';
+import { ISignal } from '@lumino/signaling';
+import { IFileChange } from './tokens';
+/**
+ * Callbacks the panel needs to delegate to (so the React component stays
+ * free of any JupyterLab application coupling). The plugin wires these up
+ * with the actual `JupyterFrontEnd` reference.
+ */
+export interface IGitPanelHandlers {
+    /** Open a diff viewer for the given file in the main area. */
+    openDiff(change: IFileChange): void;
+    /** Show a confirmation dialog. Returns true when the user accepted. */
+    confirm(title: string, body: string, accept: string): Promise<boolean>;
+    /** Show an error dialog. */
+    showError(title: string, error: Error): Promise<void>;
+}
+/**
+ * Top-level React component rendered inside the {@link GitPanel} widget.
+ * Owns the polling + refresh wiring around the `/git/status` endpoint and
+ * the small bit of UI state that controls section collapse and the
+ * in-flight per-file action spinners.
+ */
+export declare function GitPanelComponent(props: {
+    handlers: IGitPanelHandlers;
+    refreshSignal: ISignal<unknown, void>;
+}): React.ReactElement;

package/lib/git/panelComponent.js

@@ -0,0 +1,300 @@
+import * as React from 'react';
+import { add, addAll, checkout, porcelainToFileChanges, reset, resetAll, showTopLevel, status } from './api';
+/**
+ * The polling interval for the panel. We refresh the status periodically so
+ * out-of-band changes (e.g. the user runs `git add` from a terminal) become
+ * visible without requiring a manual refresh.
+ */
+const STATUS_POLL_INTERVAL_MS = 5000;
+/**
+ * Top-level React component rendered inside the {@link GitPanel} widget.
+ * Owns the polling + refresh wiring around the `/git/status` endpoint and
+ * the small bit of UI state that controls section collapse and the
+ * in-flight per-file action spinners.
+ */
+export function GitPanelComponent(props) {
+    const { handlers, refreshSignal } = props;
+    const [state, setState] = React.useState({
+        loading: true,
+        result: null,
+        error: null
+    });
+    // The absolute filesystem path of the resolved git top-level. Used purely
+    // for display in the panel header.
+    const [topLevel, setTopLevel] = React.useState(null);
+    // Per-action spinner gating: keyed by `${group}:${path}`, value is the
+    // action currently in flight. Lets the row render a disabled state on
+    // exactly the file that is being mutated, without locking the whole panel.
+    const [pendingActions, setPendingActions] = React.useState({});
+    const [stagedCollapsed, setStagedCollapsed] = React.useState(false);
+    const [changesCollapsed, setChangesCollapsed] = React.useState(false);
+    // The repo path passed to every API call. We use the JupyterLab server's
+    // root (the empty string) and let `git` resolve the enclosing repo on the
+    // server side. This works as long as the server was started inside a git
+    // repo — the common case.
+    const repoPath = '';
+    const refresh = React.useCallback(async () => {
+        var _a;
+        try {
+            const [topLevelResult, statusResult] = await Promise.all([
+                showTopLevel(repoPath),
+                status(repoPath)
+            ]);
+            setTopLevel(topLevelResult);
+            if (statusResult.code !== 0) {
+                setState({
+                    loading: false,
+                    result: null,
+                    error: (_a = statusResult.message) !== null && _a !== void 0 ? _a : 'Failed to load git status'
+                });
+                return;
+            }
+            setState({ loading: false, result: statusResult, error: null });
+        }
+        catch (err) {
+            setState({
+                loading: false,
+                result: null,
+                error: err instanceof Error ? err.message : String(err)
+            });
+        }
+    }, [repoPath]);
+    // Initial load + polling. `refresh` is stable for a given `repoPath`, so
+    // the polling interval is only re-created when the repo path changes.
+    React.useEffect(() => {
+        void refresh();
+        const interval = window.setInterval(() => void refresh(), STATUS_POLL_INTERVAL_MS);
+        return () => {
+            window.clearInterval(interval);
+        };
+    }, [refresh]);
+    // External refresh triggers (toolbar button, plugin-level events).
+    React.useEffect(() => {
+        const handler = () => {
+            void refresh();
+        };
+        refreshSignal.connect(handler);
+        return () => {
+            refreshSignal.disconnect(handler);
+        };
+    }, [refresh, refreshSignal]);
+    const runAction = React.useCallback(async (change, action, run) => {
+        const key = `${change.group}:${change.path}`;
+        setPendingActions(prev => ({ ...prev, [key]: action }));
+        try {
+            await run();
+            await refresh();
+        }
+        catch (err) {
+            await handlers.showError('Git operation failed', err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setPendingActions(prev => {
+                const next = { ...prev };
+                delete next[key];
+                return next;
+            });
+        }
+    }, [handlers, refresh]);
+    const onStage = React.useCallback((change) => runAction(change, 'stage', () => add(repoPath, change.path)), [repoPath, runAction]);
+    const onUnstage = React.useCallback((change) => runAction(change, 'unstage', () => reset(repoPath, change.path)), [repoPath, runAction]);
+    const onDiscard = React.useCallback(async (change) => {
+        const verb = change.status === 'untracked' ? 'remove' : 'restore';
+        const accepted = await handlers.confirm(verb === 'remove' ? 'Remove file' : 'Discard changes', verb === 'remove'
+            ? `Permanently remove ${change.path}? This cannot be undone.`
+            : `Discard all changes to ${change.path}? This will revert the file to its last staged version and cannot be undone.`, verb === 'remove' ? 'Remove' : 'Discard');
+        if (!accepted) {
+            return;
+        }
+        // The git extension's `checkout` endpoint without a branch reverts the
+        // working tree copy of the file to the index. For untracked files we
+        // can't checkout, so the user is told the action is unsupported and we
+        // bail out — they can delete the file via the file browser instead.
+        if (change.status === 'untracked') {
+            await handlers.showError('Cannot discard untracked file', new Error('Untracked files cannot be discarded from the git panel — delete them from the file browser instead.'));
+            return;
+        }
+        await runAction(change, 'discard', () => checkout(repoPath, change.path));
+    }, [handlers, repoPath, runAction]);
+    const onStageAll = React.useCallback(async () => {
+        try {
+            await addAll(repoPath);
+            await refresh();
+        }
+        catch (err) {
+            await handlers.showError('Stage all failed', err instanceof Error ? err : new Error(String(err)));
+        }
+    }, [handlers, refresh, repoPath]);
+    const onUnstageAll = React.useCallback(async () => {
+        try {
+            await resetAll(repoPath);
+            await refresh();
+        }
+        catch (err) {
+            await handlers.showError('Unstage all failed', err instanceof Error ? err : new Error(String(err)));
+        }
+    }, [handlers, refresh, repoPath]);
+    // Categorize the porcelain entries into the two visible groups. Because
+    // `porcelainToFileChanges` may emit two changes per file (one staged, one
+    // unstaged), the same file can show up in both lists when it has been
+    // partially staged.
+    const { staged, unstaged } = React.useMemo(() => {
+        const stagedAcc = [];
+        const unstagedAcc = [];
+        if (state.result === null) {
+            return { staged: stagedAcc, unstaged: unstagedAcc };
+        }
+        for (const file of state.result.files) {
+            for (const change of porcelainToFileChanges(file)) {
+                if (change.group === 'staged') {
+                    stagedAcc.push(change);
+                }
+                else {
+                    unstagedAcc.push(change);
+                }
+            }
+        }
+        stagedAcc.sort((a, b) => a.path.localeCompare(b.path));
+        unstagedAcc.sort((a, b) => a.path.localeCompare(b.path));
+        return { staged: stagedAcc, unstaged: unstagedAcc };
+    }, [state.result]);
+    return (React.createElement("div", { className: "jp-xtralab-GitPanel-content" },
+        React.createElement(PanelHeader, { topLevel: topLevel, result: state.result, loading: state.loading, error: state.error, onRefresh: () => void refresh() }),
+        state.error !== null ? (React.createElement("div", { className: "jp-xtralab-GitPanel-error" }, state.error)) : (React.createElement(React.Fragment, null,
+            React.createElement(ChangeSection, { label: "Staged Changes", count: staged.length, collapsed: stagedCollapsed, onToggleCollapsed: () => setStagedCollapsed(c => !c), actions: staged.length > 0
+                    ? [
+                        {
+                            label: 'Unstage all changes',
+                            symbol: '−',
+                            onClick: onUnstageAll
+                        }
+                    ]
+                    : undefined }, staged.map(change => (React.createElement(ChangeRow, { key: `${change.group}:${change.path}`, change: change, pendingAction: pendingActions[`${change.group}:${change.path}`], onClick: () => handlers.openDiff(change), actions: [
+                    {
+                        label: 'Unstage changes',
+                        symbol: '−',
+                        onClick: () => void onUnstage(change)
+                    }
+                ] })))),
+            React.createElement(ChangeSection, { label: "Changes", count: unstaged.length, collapsed: changesCollapsed, onToggleCollapsed: () => setChangesCollapsed(c => !c), actions: unstaged.length > 0
+                    ? [
+                        {
+                            label: 'Stage all changes',
+                            symbol: '+',
+                            onClick: onStageAll
+                        }
+                    ]
+                    : undefined }, unstaged.map(change => (React.createElement(ChangeRow, { key: `${change.group}:${change.path}`, change: change, pendingAction: pendingActions[`${change.group}:${change.path}`], onClick: () => handlers.openDiff(change), actions: [
+                    {
+                        label: 'Discard changes',
+                        symbol: '⟲',
+                        onClick: () => void onDiscard(change)
+                    },
+                    {
+                        label: 'Stage changes',
+                        symbol: '+',
+                        onClick: () => void onStage(change)
+                    }
+                ] })))),
+            staged.length === 0 && unstaged.length === 0 && !state.loading ? (React.createElement("div", { className: "jp-xtralab-GitPanel-empty" }, "No changes detected.")) : null))));
+}
+function PanelHeader(props) {
+    var _a;
+    const { topLevel, result, loading, error, onRefresh } = props;
+    const repoName = topLevel !== null
+        ? ((_a = topLevel
+            .split('/')
+            .filter(s => s.length > 0)
+            .pop()) !== null && _a !== void 0 ? _a : topLevel)
+        : null;
+    return (React.createElement("div", { className: "jp-xtralab-GitPanel-header" },
+        React.createElement("div", { className: "jp-xtralab-GitPanel-headerInfo" },
+            React.createElement("div", { className: "jp-xtralab-GitPanel-title" }, "Source Control"),
+            repoName !== null ? (React.createElement("div", { className: "jp-xtralab-GitPanel-repo", title: topLevel !== null && topLevel !== void 0 ? topLevel : '' }, repoName)) : null,
+            (result === null || result === void 0 ? void 0 : result.branch) !== undefined && (result === null || result === void 0 ? void 0 : result.branch) !== null ? (React.createElement("div", { className: "jp-xtralab-GitPanel-branch" },
+                result.branch,
+                result.ahead > 0 ? React.createElement("span", null,
+                    " \u2191",
+                    result.ahead) : null,
+                result.behind > 0 ? React.createElement("span", null,
+                    " \u2193",
+                    result.behind) : null)) : null),
+        React.createElement("button", { type: "button", className: "jp-xtralab-GitPanel-iconButton", title: "Refresh", disabled: loading && error === null, onClick: onRefresh }, "\u27F3")));
+}
+function ChangeSection(props) {
+    const { label, count, collapsed, onToggleCollapsed, actions, children } = props;
+    return (React.createElement("div", { className: "jp-xtralab-GitPanel-section" },
+        React.createElement("div", { className: "jp-xtralab-GitPanel-sectionHeader", onClick: onToggleCollapsed },
+            React.createElement("span", { className: "jp-xtralab-GitPanel-sectionChevron" }, collapsed ? '▸' : '▾'),
+            React.createElement("span", { className: "jp-xtralab-GitPanel-sectionLabel" }, label),
+            actions !== undefined ? (React.createElement("span", { className: "jp-xtralab-GitPanel-sectionActions" }, actions.map(action => (React.createElement("button", { key: action.label, type: "button", className: "jp-xtralab-GitPanel-iconButton", title: action.label, onClick: event => {
+                    event.stopPropagation();
+                    action.onClick();
+                } }, action.symbol))))) : null,
+            React.createElement("span", { className: "jp-xtralab-GitPanel-sectionCount" }, count)),
+        !collapsed ? (React.createElement("div", { className: "jp-xtralab-GitPanel-sectionBody" }, children)) : null));
+}
+function ChangeRow(props) {
+    const { change, pendingAction, onClick, actions } = props;
+    const filename = basename(change.path);
+    const dirname = dirnameOrEmpty(change.path);
+    return (React.createElement("div", { className: "jp-xtralab-GitPanel-row", "data-status": change.status, title: change.from !== undefined
+            ? `${change.from} → ${change.path}`
+            : change.path, onClick: onClick },
+        React.createElement("span", { className: "jp-xtralab-GitPanel-rowLabel" },
+            React.createElement("span", { className: "jp-xtralab-GitPanel-rowName" }, filename),
+            dirname !== '' ? (React.createElement("span", { className: "jp-xtralab-GitPanel-rowPath" }, dirname)) : null),
+        React.createElement("span", { className: "jp-xtralab-GitPanel-rowActions", "data-pending": pendingAction !== undefined }, actions.map(action => (React.createElement("button", { key: action.label, type: "button", className: "jp-xtralab-GitPanel-iconButton", title: action.label, disabled: pendingAction !== undefined, onClick: event => {
+                event.stopPropagation();
+                action.onClick();
+            } }, action.symbol)))),
+        React.createElement("span", { className: "jp-xtralab-GitPanel-rowBadge", "data-status": change.status, title: statusTooltip(change.status) }, statusBadge(change.status))));
+}
+function statusBadge(status) {
+    switch (status) {
+        case 'modified':
+            return 'M';
+        case 'added':
+            return 'A';
+        case 'deleted':
+            return 'D';
+        case 'renamed':
+            return 'R';
+        case 'untracked':
+            return 'U';
+        case 'unmerged':
+            return '!';
+        case 'typechange':
+            return 'T';
+        default:
+            return '?';
+    }
+}
+function statusTooltip(status) {
+    switch (status) {
+        case 'modified':
+            return 'Modified';
+        case 'added':
+            return 'Added';
+        case 'deleted':
+            return 'Deleted';
+        case 'renamed':
+            return 'Renamed';
+        case 'untracked':
+            return 'Untracked';
+        case 'unmerged':
+            return 'Unmerged (conflict)';
+        case 'typechange':
+            return 'Type changed';
+        default:
+            return 'Unknown';
+    }
+}
+function basename(path) {
+    const idx = path.lastIndexOf('/');
+    return idx < 0 ? path : path.slice(idx + 1);
+}
+function dirnameOrEmpty(path) {
+    const idx = path.lastIndexOf('/');
+    return idx < 0 ? '' : path.slice(0, idx);
+}

package/lib/git/tokens.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Types shared by the git plugin. Mirror the response shapes returned by the
+ * `jupyterlab_git` server extension's REST API so the frontend can stay
+ * tightly coupled to a single version of those endpoints.
+ */
+/**
+ * A single entry in the `files` array returned by `POST /git/<path>/status`.
+ * `x` and `y` are the porcelain-format index/worktree status codes (see
+ * `git status --porcelain`); `to` is the file's current path relative to the
+ * git repository root, `from` is the source path for renames (and equal to
+ * `to` for any other status).
+ */
+export interface IGitStatusFile {
+    x: string;
+    y: string;
+    to: string;
+    from: string;
+    is_binary: boolean | null;
+}
+/** Response shape of `POST /git/<path>/status`. */
+export interface IGitStatusResult {
+    code: number;
+    branch: string | null;
+    remote: string | null;
+    ahead: number;
+    behind: number;
+    files: IGitStatusFile[];
+    state?: number;
+    message?: string;
+}
+/**
+ * Reference accepted by `POST /git/<path>/content` to identify which version
+ * of a file to fetch. `WORKING` is the on-disk copy, `INDEX` is the staged
+ * copy, and a `git` value is any commit-ish (`HEAD`, a SHA, …).
+ */
+export type GitReference = {
+    special: 'WORKING' | 'INDEX' | 'BASE';
+} | {
+    git: string;
+};
+/**
+ * Response shape of `POST /git/<path>/content`. The server only returns text
+ * content here; binary files are reported as binary in the status response,
+ * and we surface them in the UI without attempting to render their diff.
+ */
+export interface IGitContentResult {
+    code: number;
+    content: string;
+    message?: string;
+}
+/**
+ * Where a file's change lives relative to the index.
+ *
+ *   - `staged`   → present in the index, may differ from HEAD
+ *   - `unstaged` → present in the worktree, differs from the index
+ *
+ * A single file can appear in both groups when the worktree has further
+ * changes on top of an already-staged version. The panel models that as two
+ * separate entries, one per group.
+ */
+export type FileChangeGroup = 'staged' | 'unstaged';
+/**
+ * The user-facing status of a file change. Drives the single-letter badge
+ * (M/A/D/R/U/?) shown next to each entry in the panel.
+ */
+export type FileChangeStatus = 'modified' | 'added' | 'deleted' | 'renamed' | 'untracked' | 'unmerged' | 'typechange' | 'unknown';
+/**
+ * One row in the changes panel. `path` is the file's path relative to the
+ * git repository root. `from` is non-`undefined` only for renames, in which
+ * case it carries the original path.
+ */
+export interface IFileChange {
+    path: string;
+    from?: string;
+    group: FileChangeGroup;
+    status: FileChangeStatus;
+    isBinary: boolean | null;
+}

package/lib/git/tokens.js

@@ -0,0 +1,6 @@
+/**
+ * Types shared by the git plugin. Mirror the response shapes returned by the
+ * `jupyterlab_git` server extension's REST API so the frontend can stay
+ * tightly coupled to a single version of those endpoints.
+ */
+export {};

package/lib/index.d.ts

@@ -0,0 +1,10 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+/**
+ * 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
+ * each plugin individually and only the ones whose required tokens are
+ * available end up running.
+ */
+declare const plugins: JupyterFrontEndPlugin<unknown>[];
+export default plugins;

package/lib/index.js

@@ -0,0 +1,14 @@
+import fileBrowserPlugin from './fileBrowser';
+import gitPlugin from './git';
+/**
+ * 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
+ * each plugin individually and only the ones whose required tokens are
+ * available end up running.
+ */
+const plugins = [
+    fileBrowserPlugin,
+    gitPlugin
+];
+export default plugins;