add documentation panel to completer widget

packages/completer/src/widget.ts

@@ -66,7 +66,7 @@ export class Completer extends Widget {
    * Construct a text completer menu widget.
    */
   constructor(options: Completer.IOptions) {
-    super({ node: document.createElement('ul') });
+    super({ node: document.createElement('div') });
     this._renderer = options.renderer || Completer.defaultRenderer;
     this.model = options.model || null;
     this.editor = options.editor || null;
@@ -241,6 +241,12 @@ export class Completer extends Widget {
     let active = node.querySelectorAll(`.${ITEM_CLASS}`)[this._activeIndex];
     active.classList.add(ACTIVE_CLASS);
 
+    // Add the documentation panel
+    let docPanel = document.createElement('div');
+    docPanel.className = 'jp-Completer-docpanel';
+    node.appendChild(docPanel);
+    this._updateDocPanel();
+
     // If this is the first time the current completer session has loaded,
     // populate any initial subset match.
     if (!model.query) {
@@ -294,13 +300,16 @@ export class Completer extends Widget {
     let orderedTypes = model.orderedTypes();
 
     // Populate the completer items.
+    let ul = document.createElement('ul');
+    ul.className = 'jp-Completer-list';
     for (let item of items) {
       if (!this._renderer.createCompletionItemNode) {
         return null;
       }
       let li = this._renderer.createCompletionItemNode(item, orderedTypes);
-      node.appendChild(li);
+      ul.appendChild(li);
     }
+    node.appendChild(ul);
     return node;
   }
 
@@ -338,14 +347,17 @@ export class Completer extends Widget {
     const orderedTypes = model.orderedTypes();
 
     // Populate the completer items.
+    let ul = document.createElement('ul');
+    ul.className = 'jp-Completer-list';
     for (const item of items) {
       const li = this._renderer.createItemNode(
         item!,
         model.typeMap(),
         orderedTypes
       );
-      node.appendChild(li);
+      ul.appendChild(li);
     }
+    node.appendChild(ul);
     return node;
   }
 
@@ -388,7 +400,11 @@ export class Completer extends Widget {
 
     active = items[this._activeIndex] as HTMLElement;
     active.classList.add(ACTIVE_CLASS);
-    ElementExt.scrollIntoViewIfNeeded(this.node, active);
+    let completionList = this.node.querySelector(
+      '.jp-Completer-list'
+    ) as Element;
+    ElementExt.scrollIntoViewIfNeeded(completionList, active);
+    this._updateDocPanel();
   }
 
   /**
@@ -566,6 +582,35 @@ export class Completer extends Widget {
     });
   }
 
+  /**
+   * Update the display-state and contents of the documentation panel
+   */
+  private _updateDocPanel(): void {
+    let docPanel = this.node.querySelector('.jp-Completer-docpanel');
+    if (!docPanel) {
+      return;
+    }
+    if (!this.model?.completionItems) {
+      return;
+    }
+    let items = this.model?.completionItems();
+    if (!items) {
+      docPanel.setAttribute('style', 'display:none');
+      return;
+    }
+    let activeItem = items[this._activeIndex];
+    if (!activeItem) {
+      docPanel.setAttribute('style', 'display:none');
+      return;
+    }
+    if (activeItem.documentation) {
+      docPanel.textContent = activeItem.documentation;
+      docPanel.setAttribute('style', '');
+    } else {
+      docPanel.setAttribute('style', 'display:none');
+    }
+  }
+
   private _activeIndex = 0;
   private _editor: CodeEditor.IEditor | null = null;
   private _model: Completer.IModel | null = null;

packages/completer/style/base.css

@@ -6,6 +6,7 @@
 
 :root {
   --jp-private-completer-item-height: 22px;
+  --jp-private-completer-docpanel-padding: 2px;
   /* Shift the baseline of the type character to align with the match text */
   --jp-private-completer-type-offset: 2px;
 }
@@ -15,20 +16,33 @@
   background: var(--jp-layout-color1);
   color: var(--jp-content-font-color1);
   border: var(--jp-border-width) solid var(--jp-border-color1);
-  list-style-type: none;
-  overflow-y: scroll;
-  overflow-x: auto;
   padding: 0;
+  display: flex;
+  flex-direction: row;
   /* Position the completer relative to the text editor, align the '.' */
   margin: 4px 0 0 -30px;
+  z-index: 10001;
+}
+
+.jp-Completer-docpanel {
+  border-left: var(--jp-border-width) solid var(--jp-border-color1);
+  width: 300px;
+  overflow: scroll;
+  padding: var(--jp-private-completer-docpanel-padding);
   max-height: calc(
     (10 * var(--jp-private-completer-item-height)) +
-      (2 * var(--jp-border-width))
+      (2 * var(--jp-private-completer-docpanel-padding))
   );
-  min-height: calc(
-    var(--jp-private-completer-item-height) + (2 * var(--jp-border-width))
-  );
-  z-index: 10001;
+}
+
+.jp-Completer-list {
+  margin: 0;
+  padding: 0;
+  list-style-type: none;
+  overflow-y: scroll;
+  overflow-x: auto;
+  max-height: calc((10 * var(--jp-private-completer-item-height)));
+  min-height: calc(var(--jp-private-completer-item-height));
 }
 
 .jp-Completer-item {