@jupyterlab/statusbar 4.0.0-alpha.19 → 4.0.0-alpha.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupyterlab/statusbar",
-  "version": "4.0.0-alpha.19",
+  "version": "4.0.0-alpha.20",
   "description": "JupyterLab statusbar package.",
   "homepage": "https://github.com/jupyterlab/jupyterlab",
   "bugs": {
@@ -22,7 +22,8 @@
   "files": [
     "lib/**/*.{d.ts,eot,gif,html,jpg,js,js.map,json,png,svg,woff2,ttf}",
     "style/**/*.{css,eot,gif,html,jpg,json,png,svg,woff2,ttf}",
-    "style/index.js"
+    "style/index.js",
+    "src/**/*.{ts,tsx}"
   ],
   "scripts": {
     "build": "tsc -b",
@@ -36,20 +37,20 @@
     "watch": "tsc -b --watch"
   },
   "dependencies": {
-    "@jupyterlab/ui-components": "^4.0.0-alpha.34",
-    "@lumino/algorithm": "^2.0.0-beta.0",
-    "@lumino/coreutils": "^2.0.0-beta.0",
-    "@lumino/disposable": "^2.0.0-beta.1",
-    "@lumino/messaging": "^2.0.0-beta.0",
-    "@lumino/signaling": "^2.0.0-beta.1",
-    "@lumino/widgets": "^2.0.0-beta.1",
+    "@jupyterlab/ui-components": "^4.0.0-alpha.35",
+    "@lumino/algorithm": "^2.0.0-rc.0",
+    "@lumino/coreutils": "^2.0.0-rc.0",
+    "@lumino/disposable": "^2.0.0-rc.0",
+    "@lumino/messaging": "^2.0.0-rc.0",
+    "@lumino/signaling": "^2.0.0-rc.0",
+    "@lumino/widgets": "^2.0.0-rc.0",
     "react": "^18.2.0"
   },
   "devDependencies": {
-    "@jupyterlab/testing": "^4.0.0-alpha.19",
+    "@jupyterlab/testing": "^4.0.0-alpha.20",
     "@types/jest": "^29.2.0",
     "rimraf": "~3.0.0",
-    "typescript": "~4.7.3"
+    "typescript": "~5.0.0-beta"
   },
   "publishConfig": {
     "access": "public"

package/src/components/group.tsx

@@ -0,0 +1,48 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import * as React from 'react';
+
+/**
+ * A tsx component for a set of items logically grouped together.
+ */
+export function GroupItem(
+  props: GroupItem.IProps & React.HTMLAttributes<HTMLDivElement>
+): React.ReactElement<GroupItem.IProps> {
+  const { spacing, children, className, ...rest } = props;
+  const numChildren = React.Children.count(children);
+
+  return (
+    <div className={`jp-StatusBar-GroupItem ${className}`} {...rest}>
+      {React.Children.map(children, (child, i) => {
+        if (i === 0) {
+          return <div style={{ marginRight: `${spacing}px` }}>{child}</div>;
+        } else if (i === numChildren - 1) {
+          return <div style={{ marginLeft: `${spacing}px` }}>{child}</div>;
+        } else {
+          return <div style={{ margin: `0px ${spacing}px` }}>{child}</div>;
+        }
+      })}
+    </div>
+  );
+}
+
+/**
+ * A namespace for GroupItem statics.
+ */
+export namespace GroupItem {
+  /**
+   * Props for the GroupItem.
+   */
+  export interface IProps {
+    /**
+     * The spacing, in px, between the items in the group.
+     */
+    spacing: number;
+
+    /**
+     * The items to arrange in a group.
+     */
+    children: JSX.Element[];
+  }
+}

package/src/components/hover.tsx

@@ -0,0 +1,214 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { HoverBox } from '@jupyterlab/ui-components';
+import { Message } from '@lumino/messaging';
+import { PanelLayout, Widget } from '@lumino/widgets';
+
+/**
+ * Create and show a popup component.
+ *
+ * @param options - options for the popup
+ *
+ * @returns the popup that was created.
+ */
+export function showPopup(options: Popup.IOptions): Popup {
+  const dialog = new Popup(options);
+  if (!options.startHidden) {
+    dialog.launch();
+  }
+  return dialog;
+}
+
+/**
+ * A class for a Popup widget.
+ */
+export class Popup extends Widget {
+  /**
+   * Construct a new Popup.
+   */
+  constructor(options: Omit<Popup.IOptions, 'startHidden'>) {
+    super();
+    this._body = options.body;
+    this._body.addClass('jp-StatusBar-HoverItem');
+    this._anchor = options.anchor;
+    this._align = options.align;
+    if (options.hasDynamicSize) {
+      this._observer = new ResizeObserver(() => {
+        this.update();
+      });
+    }
+    const layout = (this.layout = new PanelLayout());
+    layout.addWidget(options.body);
+    this._body.node.addEventListener('resize', () => {
+      this.update();
+    });
+  }
+
+  /**
+   * Attach the popup widget to the page.
+   */
+  launch(): void {
+    this._setGeometry();
+    Widget.attach(this, document.body);
+    this.update();
+    this._anchor.addClass('jp-mod-clicked');
+    this._anchor.removeClass('jp-mod-highlight');
+  }
+
+  /**
+   * Handle `'update'` messages for the widget.
+   */
+  protected onUpdateRequest(msg: Message): void {
+    this._setGeometry();
+    super.onUpdateRequest(msg);
+  }
+
+  /**
+   * Handle `'after-attach'` messages for the widget.
+   */
+  protected onAfterAttach(msg: Message): void {
+    document.addEventListener('click', this, false);
+    this.node.addEventListener('keydown', this, false);
+    window.addEventListener('resize', this, false);
+    this._observer?.observe(this._body.node);
+  }
+
+  /**
+   * Handle `'before-detach'` messages for the widget.
+   */
+  protected onBeforeDetach(msg: Message): void {
+    this._observer?.disconnect();
+    document.removeEventListener('click', this, false);
+    this.node.removeEventListener('keydown', this, false);
+    window.removeEventListener('resize', this, false);
+  }
+
+  /**
+   * Handle `'resize'` messages for the widget.
+   */
+  protected onResize(): void {
+    this.update();
+  }
+
+  /**
+   * Dispose of the widget.
+   */
+  dispose(): void {
+    this._observer?.disconnect();
+    super.dispose();
+    this._anchor.removeClass('jp-mod-clicked');
+    this._anchor.addClass('jp-mod-highlight');
+  }
+
+  /**
+   * Handle DOM events for the widget.
+   */
+  handleEvent(event: Event): void {
+    switch (event.type) {
+      case 'keydown':
+        this._evtKeydown(event as KeyboardEvent);
+        break;
+      case 'click':
+        this._evtClick(event as MouseEvent);
+        break;
+      case 'resize':
+        this.onResize();
+        break;
+      default:
+        break;
+    }
+  }
+
+  private _evtClick(event: MouseEvent): void {
+    if (
+      !!event.target &&
+      !(
+        this._body.node.contains(event.target as HTMLElement) ||
+        this._anchor.node.contains(event.target as HTMLElement)
+      )
+    ) {
+      this.dispose();
+    }
+  }
+
+  private _evtKeydown(event: KeyboardEvent): void {
+    // Check for escape key
+    switch (event.keyCode) {
+      case 27: // Escape.
+        event.stopPropagation();
+        event.preventDefault();
+        this.dispose();
+        break;
+      default:
+        break;
+    }
+  }
+
+  private _setGeometry(): void {
+    let aligned = 0;
+    const anchorRect = this._anchor.node.getBoundingClientRect();
+    const bodyRect = this._body.node.getBoundingClientRect();
+    if (this._align === 'right') {
+      aligned = -(bodyRect.width - anchorRect.width);
+    }
+    const style = window.getComputedStyle(this._body.node);
+    HoverBox.setGeometry({
+      anchor: anchorRect,
+      host: document.body,
+      maxHeight: 500,
+      minHeight: 20,
+      node: this._body.node,
+      offset: {
+        horizontal: aligned
+      },
+      privilege: 'forceAbove',
+      style
+    });
+  }
+
+  private _body: Widget;
+  private _anchor: Widget;
+  private _align: 'left' | 'right' | undefined;
+  private _observer: ResizeObserver | null;
+}
+
+/**
+ * A namespace for Popup statics.
+ */
+export namespace Popup {
+  /**
+   * Options for creating a Popup widget.
+   */
+  export interface IOptions {
+    /**
+     * The content of the popup.
+     */
+    body: Widget;
+
+    /**
+     * The widget to which we are attaching the popup.
+     */
+    anchor: Widget;
+
+    /**
+     * Whether to align the popup to the left or the right of the anchor.
+     */
+    align?: 'left' | 'right';
+
+    /**
+     * Whether the body has dynamic size or not.
+     * By default, this is `false`.
+     */
+    hasDynamicSize?: boolean;
+
+    /**
+     * Whether to start the popup in hidden mode or not.
+     * By default, this is `false`.
+     *
+     * ### Note
+     * The popup can be displayed using `launch` method.
+     */
+    startHidden?: boolean;
+  }
+}

package/src/components/index.ts

@@ -0,0 +1,8 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+export * from './group';
+export * from './hover';
+export * from './progressBar';
+export * from './text';
+export * from './progressCircle';

package/src/components/progressBar.tsx

@@ -0,0 +1,87 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import * as React from 'react';
+
+/**
+ * A namespace for ProgressBar statics.
+ */
+export namespace ProgressBar {
+  /**
+   * Props for the ProgressBar.
+   */
+  export interface IProps {
+    /**
+     * The current progress percentage, from 0 to 100
+     */
+    percentage: number;
+
+    /**
+     * Width of progress bar in pixel.
+     */
+    width?: number;
+
+    /**
+     * Text to show inside progress bar.
+     */
+    content?: string;
+  }
+}
+
+/**
+ * A functional tsx component for a progress bar.
+ */
+export function ProgressBar(props: ProgressBar.IProps): JSX.Element {
+  const { width, percentage, ...rest } = props;
+  return (
+    <div
+      className={'jp-Statusbar-ProgressBar-progress-bar'}
+      role="progressbar"
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-valuenow={percentage}
+    >
+      <Filler {...{ percentage, ...rest }} contentWidth={width} />
+    </div>
+  );
+}
+
+/**
+ * A namespace for Filler statics.
+ */
+namespace Filler {
+  /**
+   * Props for the Filler component.
+   */
+  export interface IProps {
+    /**
+     * The current percentage filled, from 0 to 100
+     */
+    percentage: number;
+
+    /**
+     * Width of content inside filler.
+     */
+    contentWidth?: number;
+
+    /**
+     * Text to show inside filler.
+     */
+    content?: string;
+  }
+}
+
+/**
+ * A functional tsx component for a partially filled div.
+ */
+function Filler(props: Filler.IProps) {
+  return (
+    <div
+      style={{
+        width: `${props.percentage}%`
+      }}
+    >
+      <p>{props.content}</p>
+    </div>
+  );
+}

package/src/components/progressCircle.tsx

@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import React from 'react';
+export namespace ProgressCircle {
+  /**
+   * Props for the ProgressBar.
+   */
+  export interface IProps {
+    /**
+     * The current progress percentage, from 0 to 100
+     */
+    progress: number;
+    /**
+     * The aria-label for the widget
+     */
+    label?: string;
+    /**
+     * Element width
+     */
+    width?: number;
+    /**
+     * Element height
+     */
+    height?: number;
+  }
+}
+
+export function ProgressCircle(props: ProgressCircle.IProps): JSX.Element {
+  const radius = 104;
+  const d = (progress: number): string => {
+    const angle = Math.max(progress * 3.6, 0.1);
+    const rad = (angle * Math.PI) / 180,
+      x = Math.sin(rad) * radius,
+      y = Math.cos(rad) * -radius,
+      mid = angle < 180 ? 1 : 0,
+      shape =
+        `M 0 0 v -${radius} A ${radius} ${radius} 1 ` +
+        mid +
+        ' 0 ' +
+        x.toFixed(4) +
+        ' ' +
+        y.toFixed(4) +
+        ' z';
+    return shape;
+  };
+  return (
+    <div
+      className={'jp-Statusbar-ProgressCircle'}
+      role="progressbar"
+      aria-label={props.label || 'Unlabelled progress circle'}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-valuenow={props.progress}
+    >
+      <svg viewBox="0 0 250 250">
+        <circle
+          cx="125"
+          cy="125"
+          r={`${radius}`}
+          stroke="var(--jp-inverse-layout-color3)"
+          strokeWidth="20"
+          fill="none"
+        />
+        <path
+          transform="translate(125,125) scale(.9)"
+          d={d(props.progress)}
+          fill={'var(--jp-inverse-layout-color3)'}
+        />
+      </svg>
+    </div>
+  );
+}

package/src/components/text.tsx

@@ -0,0 +1,42 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import * as React from 'react';
+
+/**
+ * A namespace for TextItem statics.
+ */
+export namespace TextItem {
+  /**
+   * Props for a TextItem.
+   */
+  export interface IProps {
+    /**
+     * The content of the text item.
+     */
+    source: string | number;
+
+    /**
+     * Hover text to give to the node.
+     */
+    title?: string;
+  }
+}
+
+/**
+ * A functional tsx component for a text item.
+ */
+export function TextItem(
+  props: TextItem.IProps & React.HTMLAttributes<HTMLSpanElement>
+): React.ReactElement<TextItem.IProps> {
+  const { title, source, className, ...rest } = props;
+  return (
+    <span
+      className={`jp-StatusBar-TextItem ${className}`}
+      title={title}
+      {...rest}
+    >
+      {source}
+    </span>
+  );
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/* -----------------------------------------------------------------------------
+| Copyright (c) Jupyter Development Team.
+| Distributed under the terms of the Modified BSD License.
+|----------------------------------------------------------------------------*/
+/**
+ * @packageDocumentation
+ * @module statusbar
+ */
+
+export * from './components';
+export * from './statusbar';
+export * from './tokens';

package/src/statusbar.ts

@@ -0,0 +1,185 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { ArrayExt } from '@lumino/algorithm';
+import {
+  DisposableDelegate,
+  DisposableSet,
+  IDisposable
+} from '@lumino/disposable';
+import { Message } from '@lumino/messaging';
+import { Panel, PanelLayout, Widget } from '@lumino/widgets';
+import { IStatusBar } from './tokens';
+
+/**
+ * Main status bar object which contains all items.
+ */
+export class StatusBar extends Widget implements IStatusBar {
+  constructor() {
+    super();
+    this.addClass('jp-StatusBar-Widget');
+
+    const rootLayout = (this.layout = new PanelLayout());
+
+    const leftPanel = (this._leftSide = new Panel());
+    const middlePanel = (this._middlePanel = new Panel());
+    const rightPanel = (this._rightSide = new Panel());
+
+    leftPanel.addClass('jp-StatusBar-Left');
+    middlePanel.addClass('jp-StatusBar-Middle');
+    rightPanel.addClass('jp-StatusBar-Right');
+
+    rootLayout.addWidget(leftPanel);
+    rootLayout.addWidget(middlePanel);
+    rootLayout.addWidget(rightPanel);
+  }
+
+  /**
+   * Register a new status item.
+   *
+   * @param id - a unique id for the status item.
+   *
+   * @param statusItem - The item to add to the status bar.
+   */
+  registerStatusItem(id: string, statusItem: IStatusBar.IItem): IDisposable {
+    if (id in this._statusItems) {
+      throw new Error(`Status item ${id} already registered.`);
+    }
+
+    // Populate defaults for the optional properties of the status item.
+    const fullStatusItem = {
+      ...Private.statusItemDefaults,
+      ...statusItem
+    } as Private.IFullItem;
+    const { align, item, rank } = fullStatusItem;
+
+    // Connect the activeStateChanged signal to refreshing the status item,
+    // if the signal was provided.
+    const onActiveStateChanged = () => {
+      this._refreshItem(id);
+    };
+    if (fullStatusItem.activeStateChanged) {
+      fullStatusItem.activeStateChanged.connect(onActiveStateChanged);
+    }
+
+    const rankItem = { id, rank };
+
+    fullStatusItem.item.addClass('jp-StatusBar-Item');
+    this._statusItems[id] = fullStatusItem;
+
+    if (align === 'left') {
+      const insertIndex = this._findInsertIndex(this._leftRankItems, rankItem);
+      if (insertIndex === -1) {
+        this._leftSide.addWidget(item);
+        this._leftRankItems.push(rankItem);
+      } else {
+        ArrayExt.insert(this._leftRankItems, insertIndex, rankItem);
+        this._leftSide.insertWidget(insertIndex, item);
+      }
+    } else if (align === 'right') {
+      const insertIndex = this._findInsertIndex(this._rightRankItems, rankItem);
+      if (insertIndex === -1) {
+        this._rightSide.addWidget(item);
+        this._rightRankItems.push(rankItem);
+      } else {
+        ArrayExt.insert(this._rightRankItems, insertIndex, rankItem);
+        this._rightSide.insertWidget(insertIndex, item);
+      }
+    } else {
+      this._middlePanel.addWidget(item);
+    }
+    this._refreshItem(id); // Initially refresh the status item.
+
+    const disposable = new DisposableDelegate(() => {
+      delete this._statusItems[id];
+      if (fullStatusItem.activeStateChanged) {
+        fullStatusItem.activeStateChanged.disconnect(onActiveStateChanged);
+      }
+      item.parent = null;
+      item.dispose();
+    });
+    this._disposables.add(disposable);
+    return disposable;
+  }
+
+  /**
+   * Dispose of the status bar.
+   */
+  dispose(): void {
+    this._leftRankItems.length = 0;
+    this._rightRankItems.length = 0;
+    this._disposables.dispose();
+    super.dispose();
+  }
+
+  /**
+   * Handle an 'update-request' message to the status bar.
+   */
+  protected onUpdateRequest(msg: Message): void {
+    this._refreshAll();
+    super.onUpdateRequest(msg);
+  }
+
+  private _findInsertIndex(
+    side: Private.IRankItem[],
+    newItem: Private.IRankItem
+  ): number {
+    return ArrayExt.findFirstIndex(side, item => item.rank > newItem.rank);
+  }
+
+  private _refreshItem(id: string) {
+    const statusItem = this._statusItems[id];
+    if (statusItem.isActive()) {
+      statusItem.item.show();
+      statusItem.item.update();
+    } else {
+      statusItem.item.hide();
+    }
+  }
+
+  private _refreshAll(): void {
+    Object.keys(this._statusItems).forEach(id => {
+      this._refreshItem(id);
+    });
+  }
+
+  private _leftRankItems: Private.IRankItem[] = [];
+  private _rightRankItems: Private.IRankItem[] = [];
+  private _statusItems: { [id: string]: Private.IFullItem } = {};
+  private _disposables = new DisposableSet();
+  private _leftSide: Panel;
+  private _middlePanel: Panel;
+  private _rightSide: Panel;
+}
+
+/**
+ * A namespace for private functionality.
+ */
+namespace Private {
+  type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
+  /**
+   * Default options for a status item, less the item itself.
+   */
+  export const statusItemDefaults: Omit<IStatusBar.IItem, 'item'> = {
+    align: 'left',
+    rank: 0,
+    isActive: () => true,
+    activeStateChanged: undefined
+  };
+
+  /**
+   * An interface for storing the rank of a status item.
+   */
+  export interface IRankItem {
+    id: string;
+    rank: number;
+  }
+
+  export type DefaultKeys = 'align' | 'rank' | 'isActive';
+
+  /**
+   * Type of statusbar item with defaults filled in.
+   */
+  export type IFullItem = Required<Pick<IStatusBar.IItem, DefaultKeys>> &
+    Omit<IStatusBar.IItem, DefaultKeys>;
+}

package/src/tokens.ts

@@ -0,0 +1,67 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { Token } from '@lumino/coreutils';
+import { IDisposable } from '@lumino/disposable';
+import { ISignal } from '@lumino/signaling';
+import { Widget } from '@lumino/widgets';
+
+// tslint:disable-next-line:variable-name
+export const IStatusBar = new Token<IStatusBar>(
+  '@jupyterlab/statusbar:IStatusBar'
+);
+
+/**
+ * Main status bar object which contains all widgets.
+ */
+export interface IStatusBar {
+  /**
+   * Register a new status item.
+   *
+   * @param id - a unique id for the status item.
+   *
+   * @param options - The options for how to add the status item.
+   *
+   * @returns an `IDisposable` that can be disposed to remove the item.
+   */
+  registerStatusItem(id: string, statusItem: IStatusBar.IItem): IDisposable;
+}
+
+/**
+ * A namespace for status bar statics.
+ */
+export namespace IStatusBar {
+  export type Alignment = 'right' | 'left' | 'middle';
+
+  /**
+   * Options for status bar items.
+   */
+  export interface IItem {
+    /**
+     * The item to add to the status bar.
+     */
+    item: Widget;
+
+    /**
+     * Which side to place item.
+     * Permanent items are intended for the right and left side,
+     * with more transient items in the middle.
+     */
+    align?: Alignment;
+
+    /**
+     *  Ordering of Items -- higher rank items are closer to the middle.
+     */
+    rank?: number;
+
+    /**
+     * Whether the item is shown or hidden.
+     */
+    isActive?: () => boolean;
+
+    /**
+     * A signal that is fired when the item active state changes.
+     */
+    activeStateChanged?: ISignal<any, void>;
+  }
+}