xtralab 0.4.0 → 0.6.0

package/src/terminals/widget.tsx

@@ -0,0 +1,240 @@
+import {
+  type TranslationBundle,
+  nullTranslator
+} from '@jupyterlab/translation';
+import {
+  addIcon,
+  closeIcon,
+  LabIcon,
+  ReactWidget,
+  stopIcon,
+  terminalIcon,
+  UseSignal
+} from '@jupyterlab/ui-components';
+import * as React from 'react';
+
+import { SessionRegistry } from './model';
+
+/**
+ * Id of the panel widget. Used for layout restoration and as the handle
+ * the sidebar visibility toggle would target.
+ */
+export const RUNNING_TERMINALS_ID = 'xtralab-running-terminals';
+
+/**
+ * Left-sidebar panel listing every running terminal session. It is the
+ * sidebar counterpart of the launcher's terminal tiles: where the
+ * launcher *starts* sessions, this panel surfaces the ones already
+ * running so the user can jump back to a backgrounded agent — including
+ * sessions whose tab has been closed but which are still alive on the
+ * server.
+ *
+ * Backed by {@link SessionRegistry}: a `UseSignal` re-renders the list
+ * whenever the registry emits `stateChanged`, so it tracks
+ * `runningChanged` and the agent-title cache without any local state.
+ * Click behaviour (activate vs. reopen, shutdown, new terminal) is
+ * delegated to plugin-supplied callbacks so the widget never imports
+ * `app`.
+ */
+export class RunningTerminals extends ReactWidget {
+  constructor(options: RunningTerminals.IOptions) {
+    super();
+    this._registry = options.registry;
+    this._trans = options.trans ?? nullTranslator.load('jupyterlab');
+    this._iconForCommand = options.iconForCommand;
+    this._onActivate = options.onActivate;
+    this._onShutdown = options.onShutdown;
+    this._onShutdownAll = options.onShutdownAll;
+    this._onCreate = options.onCreate;
+
+    this.id = RUNNING_TERMINALS_ID;
+    this.title.icon = terminalIcon;
+    this.title.caption = this._trans.__('Running Terminals');
+    this.addClass('jp-xtralab-Terminals');
+  }
+
+  dispose(): void {
+    if (this.isDisposed) {
+      return;
+    }
+    // The panel owns the registry, so tear down its upstream
+    // subscriptions before the React tree goes away.
+    this._registry.dispose();
+    super.dispose();
+  }
+
+  protected render(): React.ReactElement {
+    return (
+      <UseSignal signal={this._registry.stateChanged}>
+        {() => (
+          <RunningTerminalsComponent
+            registry={this._registry}
+            trans={this._trans}
+            iconForCommand={this._iconForCommand}
+            onActivate={this._onActivate}
+            onShutdown={this._onShutdown}
+            onShutdownAll={this._onShutdownAll}
+            onCreate={this._onCreate}
+          />
+        )}
+      </UseSignal>
+    );
+  }
+
+  private _registry: SessionRegistry;
+  private _trans: TranslationBundle;
+  private _iconForCommand: (command: string | null) => LabIcon;
+  private _onActivate: (sessionName: string) => void;
+  private _onShutdown: (sessionName: string) => void;
+  private _onShutdownAll: () => void;
+  private _onCreate: (anchor: { x: number; y: number }) => void;
+}
+
+export namespace RunningTerminals {
+  export interface IOptions {
+    registry: SessionRegistry;
+    trans?: TranslationBundle;
+    /**
+     * Resolve the running-agent command for a row (from
+     * `registry.agentCommandFor`) to the icon to show before its label —
+     * the agent's logo, or the plain terminal icon. Supplied by the plugin
+     * so the widget never imports the agent list.
+     */
+    iconForCommand: (command: string | null) => LabIcon;
+    /**
+     * Activate the named session's open tab, or reopen it in a fresh
+     * terminal widget if no tab is currently attached.
+     */
+    onActivate: (sessionName: string) => void;
+    /** Shut the named session down on the server. */
+    onShutdown: (sessionName: string) => void;
+    /**
+     * Shut down every running terminal at once. The plugin is expected to
+     * confirm with the user first, since it tears down all live sessions.
+     */
+    onShutdownAll: () => void;
+    /**
+     * Activate the "+" button, anchored at the given viewport coordinates
+     * (the bottom-left of the button). The plugin decides what to show
+     * there — a menu of agents plus a plain terminal, or just a new
+     * terminal when no agents are available — so the panel only reports
+     * where the button is and never imports the command/menu machinery.
+     */
+    onCreate: (anchor: { x: number; y: number }) => void;
+  }
+}
+
+function RunningTerminalsComponent(props: {
+  registry: SessionRegistry;
+  trans: TranslationBundle;
+  iconForCommand: (command: string | null) => LabIcon;
+  onActivate: (sessionName: string) => void;
+  onShutdown: (sessionName: string) => void;
+  onShutdownAll: () => void;
+  onCreate: (anchor: { x: number; y: number }) => void;
+}): React.ReactElement {
+  const {
+    registry,
+    trans,
+    iconForCommand,
+    onActivate,
+    onShutdown,
+    onShutdownAll,
+    onCreate
+  } = props;
+  const names = registry.sessionNames();
+  // The session whose terminal is the current widget in the main area, so its
+  // row can be highlighted. `null` when the current tab is a notebook or any
+  // other non-terminal widget.
+  const currentName = registry.currentSessionName();
+
+  return (
+    <div className="jp-xtralab-Terminals-body">
+      <div className="jp-xtralab-Terminals-header">
+        <h2 className="jp-xtralab-Terminals-title">{trans.__('Terminals')}</h2>
+        <div className="jp-xtralab-Terminals-actions">
+          <button
+            type="button"
+            className="jp-xtralab-Terminals-action jp-xtralab-Terminals-shutdown-all"
+            onClick={onShutdownAll}
+            disabled={names.length === 0}
+            title={trans.__('Shut Down All Terminals')}
+            aria-label={trans.__('Shut Down All Terminals')}
+          >
+            <stopIcon.react tag="span" verticalAlign="middle" />
+          </button>
+          <button
+            type="button"
+            className="jp-xtralab-Terminals-action jp-xtralab-Terminals-new"
+            onClick={event => {
+              // Anchor whatever the plugin shows (usually an agent menu) to
+              // the button's bottom-left, in viewport coordinates — what
+              // `Menu.open(x, y)` expects.
+              const rect = event.currentTarget.getBoundingClientRect();
+              onCreate({ x: rect.left, y: rect.bottom });
+            }}
+            title={trans.__('New Terminal')}
+            aria-label={trans.__('New Terminal')}
+            aria-haspopup="menu"
+          >
+            <addIcon.react tag="span" verticalAlign="middle" />
+          </button>
+        </div>
+      </div>
+      {names.length === 0 ? (
+        <p className="jp-xtralab-Terminals-empty">
+          {trans.__('No running terminals.')}
+        </p>
+      ) : (
+        <ul className="jp-xtralab-Terminals-list">
+          {names.map(name => {
+            const label = registry.labelFor(name);
+            const hasWidget = registry.widgetFor(name) !== null;
+            const tooltip = hasWidget
+              ? trans.__('Activate %1', label)
+              : trans.__('Reopen %1', label);
+            // The running agent's logo (e.g. Claude), or the plain terminal
+            // icon when nothing recognised is running in the session.
+            const RowIcon = iconForCommand(
+              registry.agentCommandFor(name)
+            ).react;
+            const isCurrent = name === currentName;
+            return (
+              <li
+                key={name}
+                className={
+                  isCurrent
+                    ? 'jp-xtralab-Terminals-item jp-mod-current'
+                    : 'jp-xtralab-Terminals-item'
+                }
+              >
+                <button
+                  type="button"
+                  className="jp-xtralab-Terminals-item-activate"
+                  onClick={() => onActivate(name)}
+                  title={tooltip}
+                  aria-label={tooltip}
+                  aria-current={isCurrent || undefined}
+                >
+                  <RowIcon tag="span" verticalAlign="middle" />
+                  <span className="jp-xtralab-Terminals-item-label">
+                    {label}
+                  </span>
+                </button>
+                <button
+                  type="button"
+                  className="jp-xtralab-Terminals-item-close"
+                  onClick={() => onShutdown(name)}
+                  title={trans.__('Shut down %1', label)}
+                  aria-label={trans.__('Shut down %1', label)}
+                >
+                  <closeIcon.react tag="span" verticalAlign="middle" />
+                </button>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/topBar/icons.ts

@@ -0,0 +1,30 @@
+import { LabIcon } from '@jupyterlab/ui-components';
+
+/**
+ * Mirror-symmetric "toggle sidebar" marks for the top-bar buttons, in the
+ * same visual language as the macOS / VS Code / svgrepo sidebar icons
+ * (https://www.svgrepo.com/vectors/sidebar/): a rounded window outline split
+ * by a divider, with the controlled side shaded so left vs. right reads at a
+ * glance. The artwork is hand-authored from basic geometry (rounded rect +
+ * divider + a shaded panel) so there is no third-party licensing to track,
+ * and every stroke/fill uses `currentColor` so the icons inherit the top
+ * bar's text color across the light and dark themes.
+ */
+
+export const leftSidebarIcon = new LabIcon({
+  name: 'xtralab:sidebar-left',
+  svgstr: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+  <path d="M9 3H5.5A2.5 2.5 0 0 0 3 5.5V18.5A2.5 2.5 0 0 0 5.5 21H9Z" fill="currentColor" fill-opacity="0.3"/>
+  <rect x="3" y="3" width="18" height="18" rx="2.5" stroke="currentColor" stroke-width="1.7"/>
+  <line x1="9" y1="3" x2="9" y2="21" stroke="currentColor" stroke-width="1.7"/>
+</svg>`
+});
+
+export const rightSidebarIcon = new LabIcon({
+  name: 'xtralab:sidebar-right',
+  svgstr: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+  <path d="M15 3H18.5A2.5 2.5 0 0 1 21 5.5V18.5A2.5 2.5 0 0 1 18.5 21H15Z" fill="currentColor" fill-opacity="0.3"/>
+  <rect x="3" y="3" width="18" height="18" rx="2.5" stroke="currentColor" stroke-width="1.7"/>
+  <line x1="15" y1="3" x2="15" y2="21" stroke="currentColor" stroke-width="1.7"/>
+</svg>`
+});

package/src/topBar/index.ts

@@ -0,0 +1,121 @@
+import {
+  ILabShell,
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { CommandToolbarButton, LabIcon } from '@jupyterlab/ui-components';
+
+import { leftSidebarIcon, rightSidebarIcon } from './icons';
+
+const PLUGIN_ID = 'xtralab:top-bar';
+
+/**
+ * Upstream commands from `@jupyterlab/application-extension` that collapse or
+ * expand the side areas. We bind the buttons to these rather than
+ * reimplementing the toggle, so behavior (and the `isToggled`/`isEnabled`
+ * state the buttons reflect) stays in lockstep with the View menu entries
+ * and their keyboard shortcuts.
+ */
+const TOGGLE_LEFT_AREA = 'application:toggle-left-area';
+const TOGGLE_RIGHT_AREA = 'application:toggle-right-area';
+
+interface IButtonSpec {
+  /** Stable widget id (required by `LabShell.add`). */
+  id: string;
+  /** Command the button triggers and mirrors the state of. */
+  command: string;
+  icon: LabIcon;
+  caption: (trans: ReturnType<ITranslator['load']>) => string;
+  /**
+   * Rank within the `top` area. The main menu bar is added at rank 100, so a
+   * negative rank lands the left button at the leading edge before it; a large
+   * rank puts the right button after the menu, where `margin-left: auto`
+   * (style/topBar.css) floats it to the far edge. xtralab's shipped config
+   * disables the upstream Jupyter logo that otherwise occupies rank 0, so the
+   * leading edge is free.
+   */
+  rank: number;
+  /** Side-specific class, used by the stylesheet for placement. */
+  sideClass: string;
+}
+
+const BUTTONS: IButtonSpec[] = [
+  {
+    id: 'xtralab-toggle-left-sidebar',
+    command: TOGGLE_LEFT_AREA,
+    icon: leftSidebarIcon,
+    caption: trans => trans.__('Toggle left sidebar'),
+    rank: -1,
+    sideClass: 'xtralab-TopBarButton-left'
+  },
+  {
+    id: 'xtralab-toggle-right-sidebar',
+    command: TOGGLE_RIGHT_AREA,
+    icon: rightSidebarIcon,
+    caption: trans => trans.__('Toggle right sidebar'),
+    rank: 1000,
+    sideClass: 'xtralab-TopBarButton-right'
+  }
+];
+
+/**
+ * Add two icon buttons to the top bar that toggle the left and right side
+ * areas, mirroring the macOS-style sidebar buttons: a left-sidebar button at
+ * the leading edge and a right-sidebar button at the far edge.
+ *
+ * Each is a `CommandToolbarButton` wrapping an existing
+ * `application:toggle-{left,right}-area` command, so clicking it runs the
+ * same toggle as the View menu and the button reflects the command's state —
+ * pressed while the matching sidebar is open, and disabled when the area is
+ * empty. Note xtralab ships nothing in the right area by default (the
+ * property inspector, table of contents and debugger are all disabled), so
+ * the right button stays disabled until a widget is moved or added there.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description: 'Add left and right sidebar toggle buttons to the top bar.',
+  autoStart: true,
+  requires: [ILabShell],
+  optional: [ITranslator],
+  activate: (
+    app: JupyterFrontEnd,
+    labShell: ILabShell,
+    translator: ITranslator | null
+  ): void => {
+    const { commands } = app;
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+
+    // Defer to `app.restored` so the upstream toggle commands are already in
+    // the registry: `CommandToolbarButton` renders nothing until its command
+    // exists and only re-renders on `commandChanged` of type `changed` /
+    // `many-changed` (not `added`), so mounting earlier could leave a button
+    // blank until the next unrelated command change.
+    void app.restored.then(() => {
+      for (const spec of BUTTONS) {
+        const button = new CommandToolbarButton({
+          commands,
+          id: spec.command,
+          icon: spec.icon,
+          // Empty label keeps the button icon-only: the override is forwarded
+          // verbatim and the component skips the label span when it is falsy.
+          label: '',
+          caption: spec.caption(trans),
+          // Toggle on mousedown without focusing the button. Otherwise
+          // ToolbarButtonComponent calls `event.target.focus()` on click,
+          // leaving the stealth button showing a focus fill/outline (the
+          // stray "border") until you click elsewhere — unwanted chrome for a
+          // title-bar control. Keyboard Tab focus still works, so this stays
+          // accessible.
+          noFocusOnClick: true
+        });
+        button.id = spec.id;
+        button.addClass('xtralab-TopBarButton');
+        button.addClass(spec.sideClass);
+        labShell.add(button, 'top', { rank: spec.rank });
+      }
+    });
+  }
+};
+
+export default plugin;