xtralab 0.14.1 → 0.15.1

package/src/customPanel/index.ts

@@ -0,0 +1,119 @@
+import {
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import {
+  IMovableSectionDestination,
+  IMovableSectionRegistry
+} from '@jupyterlab/apputils';
+import {
+  ITranslator,
+  nullTranslator,
+  type TranslationBundle
+} from '@jupyterlab/translation';
+import { SidePanel, tableRowsIcon } from '@jupyterlab/ui-components';
+import { ISignal, Signal } from '@lumino/signaling';
+import { AccordionPanel, Widget } from '@lumino/widgets';
+
+const PLUGIN_ID = 'xtralab:custom-panel';
+
+const CUSTOM_PANEL_ID = 'xtralab-custom-panel';
+
+/**
+ * A sidebar panel holding only the sections moved in from other panels.
+ */
+class CustomPanel extends SidePanel implements IMovableSectionDestination {
+  constructor(options: { trans: TranslationBundle }) {
+    super();
+    this.id = CUSTOM_PANEL_ID;
+    this.title.icon = tableRowsIcon;
+    this.title.caption = options.trans.__('Custom Panel');
+    this.addClass('jp-xtralab-CustomPanel');
+  }
+
+  /**
+   * The accordion panel hosting the sections.
+   */
+  get accordionPanel(): AccordionPanel {
+    return this.content as AccordionPanel;
+  }
+
+  /**
+   * The section widgets currently hosted by the panel.
+   */
+  get sections(): ReadonlyArray<Widget> {
+    return this.content.widgets;
+  }
+
+  /**
+   * A signal emitted with the new count when the number of sections changes.
+   */
+  get sectionCountChanged(): ISignal<this, number> {
+    return this._sectionCountChanged;
+  }
+
+  /**
+   * Add a section widget to the panel.
+   */
+  addSection(widget: Widget): void {
+    this.addWidget(widget);
+    this._sectionCountChanged.emit(this.content.widgets.length);
+  }
+
+  /**
+   * Remove a section widget from the panel, if it is hosted here.
+   */
+  removeSectionWidget(widget: Widget): void {
+    if (widget.parent !== this.content) {
+      return;
+    }
+    widget.parent = null;
+    this._sectionCountChanged.emit(this.content.widgets.length);
+  }
+
+  private _sectionCountChanged = new Signal<this, number>(this);
+}
+
+/**
+ * Registers "Custom Panel", which takes a sidebar tab only while it hosts a
+ * section.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description:
+    'A user-assembled sidebar panel hosting sections moved in from other panels; hidden while empty.',
+  autoStart: true,
+  optional: [IMovableSectionRegistry, ITranslator],
+  activate: (
+    app: JupyterFrontEnd,
+    registry: IMovableSectionRegistry | null,
+    translator: ITranslator | null
+  ): void => {
+    if (!registry) {
+      return;
+    }
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+    const panel = new CustomPanel({ trans });
+
+    // Only a user move should switch the sidebar, not the startup restoration.
+    let restored = false;
+    void app.restored.then(() => {
+      restored = true;
+    });
+
+    panel.sectionCountChanged.connect((_, count) => {
+      if (count > 0 && !panel.parent) {
+        app.shell.add(panel, 'left', { rank: 3 });
+        if (restored) {
+          app.shell.activateById(panel.id);
+        }
+      } else if (count === 0 && panel.parent) {
+        panel.parent = null;
+      }
+    });
+
+    registry.registerTarget(PLUGIN_ID, trans.__('Custom Panel'), panel);
+  }
+};
+
+export default plugin;

package/src/editorBreadcrumbs/index.ts

@@ -21,6 +21,10 @@ const PLUGIN_ID = 'xtralab:editor-breadcrumbs';
 const EDITOR_FACTORY = 'Editor';
 const TOOLBAR_ITEM_NAME = 'xtralab-editor-breadcrumbs';
 
+/**
+ * A widget extension that adds an `EditorBreadcrumbs` item to the toolbar of
+ * each new editor widget.
+ */
 class EditorBreadcrumbsExtension implements DocumentRegistry.IWidgetExtension<
   IDocumentWidget<Widget, DocumentRegistry.IModel>,
   DocumentRegistry.IModel
@@ -30,6 +34,9 @@ class EditorBreadcrumbsExtension implements DocumentRegistry.IWidgetExtension<
     this._trans = trans;
   }
 
+  /**
+   * Create the breadcrumbs toolbar item for a new editor widget.
+   */
   createNew(
     widget: IDocumentWidget<Widget, DocumentRegistry.IModel>,
     context: DocumentRegistry.IContext<DocumentRegistry.IModel>
@@ -56,12 +63,9 @@ class EditorBreadcrumbsExtension implements DocumentRegistry.IWidgetExtension<
 }
 
 /**
- * Adds a VS Code-style path breadcrumb to text editor toolbars. Each
- * segment is clickable: clicking dispatches `xtralab:reveal-path` so
- * any plugin that listens (today, the file browser) can surface the
- * underlying folder or file. The breadcrumbs plugin therefore does not
- * import the file browser at all — the JupyterLab command registry is
- * the only seam between them.
+ * Adds a clickable path breadcrumb to text editor toolbars. Clicks dispatch
+ * `xtralab:reveal-path`; the command registry is the only seam with the file
+ * browser.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,

package/src/editorBreadcrumbs/widget.ts

@@ -15,15 +15,25 @@ const CURRENT_ITEM_CLASS = 'jp-mod-current';
 const SEPARATOR_CLASS = 'jp-BreadCrumbs-separator';
 
 /**
- * Command dispatched when the user clicks a breadcrumb segment.
- * Registered by the file browser plugin; the breadcrumbs only know
- * the name so they stay decoupled from the file browser internals.
+ * Registered by the file browser plugin; only the name is shared here.
  */
 const REVEAL_COMMAND = 'xtralab:reveal-path';
 
+/**
+ * The options used to create an `EditorBreadcrumbs` widget.
+ */
 interface IEditorBreadcrumbsOptions {
+  /**
+   * The document context whose path is rendered.
+   */
   context: DocumentRegistry.IContext<DocumentRegistry.IModel>;
+  /**
+   * The command registry used to dispatch the reveal command.
+   */
   commands: CommandRegistry;
+  /**
+   * The application translation bundle.
+   */
   trans: TranslationBundle;
 }
 
@@ -38,9 +48,8 @@ export class EditorBreadcrumbs extends Widget {
     this._commands = options.commands;
     this._trans = options.trans;
     this.addClass(EDITOR_BREADCRUMBS_CLASS);
-    // The breadcrumbs stretch to fill the toolbar, so ReactiveToolbar's
-    // overflow math must count them as a spacer (2px) — measured at their
-    // stretched clientWidth they would evict every item into the popup.
+    // ReactiveToolbar must count the stretched breadcrumbs as a spacer (2px);
+    // measured at clientWidth they would evict every item into the popup.
     this.addClass(TOOLBAR_SPACER_CLASS);
     this.node.setAttribute('aria-label', this._trans.__('Editor file path'));
 
@@ -55,6 +64,9 @@ export class EditorBreadcrumbs extends Widget {
     this._render();
   }
 
+  /**
+   * Dispose of the resources held by the widget.
+   */
   dispose(): void {
     if (this.isDisposed) {
       return;
@@ -81,9 +93,7 @@ export class EditorBreadcrumbs extends Widget {
     parts.forEach((part, index) => {
       const isLast = index === parts.length - 1;
       const subPath = parts.slice(0, index + 1).join('/');
-      // Canonical `@pierre/trees` paths: directories carry a trailing
-      // slash, files do not. Every part except the last names a folder
-      // along the way to the open file.
+      // Canonical @pierre/trees paths: directories carry a trailing slash.
       const canonical = isLast ? subPath : `${subPath}/`;
 
       const item = document.createElement('span');
@@ -117,19 +127,15 @@ export class EditorBreadcrumbs extends Widget {
     item.dataset.path = '/';
     item.tabIndex = 0;
     item.setAttribute('role', 'button');
-    // Empty canonical path: the reveal command treats this as the
-    // workspace-root gesture — surface the file browser, clear its
-    // selection, and scroll back to the top. The tree has no row for
-    // the workspace root itself.
+    // Empty path is the workspace-root gesture; the tree has no row for
+    // the root itself.
     this._attachReveal(item, '');
     return item;
   }
 
   /**
-   * Bind click and keyboard activation on a crumb element to the
-   * shared reveal command. Dispatch is best-effort: a failure to
-   * resolve or execute the command is logged but never thrown into
-   * the editor's toolbar.
+   * Bind click and keyboard activation on a crumb to the reveal command;
+   * dispatch failures are logged, never thrown into the toolbar.
    */
   private _attachReveal(element: HTMLElement, canonicalPath: string): void {
     const fire = (event: Event): void => {

package/src/editorIndent/index.ts

@@ -14,10 +14,8 @@ import detectIndent from 'detect-indent';
 const PLUGIN_ID = 'xtralab:editor-indent';
 
 /**
- * Mime types whose newly-created (or too-short-to-detect) files should default
- * to a 2-space indent. Matches Prettier's defaults for web languages; mime
- * types not listed here inherit whatever the user has set in JupyterLab.
- * Covers .ts/.tsx/.jsx/.js variants registered by `@jupyterlab/codemirror`.
+ * 2-space fallback for new or undetectable files, matching Prettier's
+ * web-language defaults; unlisted mime types keep the user's setting.
  */
 const FALLBACK_INDENT_BY_MIME: Record<string, number> = {
   'application/ecmascript': 2,
@@ -38,15 +36,20 @@ const FALLBACK_INDENT_BY_MIME: Record<string, number> = {
   'text/yaml': 2
 };
 
+/**
+ * The indentation resolved for a document.
+ */
 interface IResolvedIndent {
+  /**
+   * The string inserted per indent level (spaces or a tab), for `indentUnit`.
+   */
   unit: string;
+  /**
+   * The indent width in columns, for `EditorState.tabSize`.
+   */
   width: number;
 }
 
-/**
- * Run `detect-indent` against the file's content and convert its result into
- * something we can hand to CodeMirror.
- */
 function detectFromContent(text: string): IResolvedIndent | null {
   if (text.length === 0) {
     return null;
@@ -76,9 +79,8 @@ function resolveIndent(text: string, mimeType: string): IResolvedIndent | null {
 }
 
 function buildExtension(resolved: IResolvedIndent): Extension {
-  // `Prec.highest` keeps these values first in their respective facets so
-  // they beat both `defaultConfig` and per-editor `editorConfig.indentUnit`,
-  // both of which JupyterLab registers at default precedence.
+  // `Prec.highest` beats both `defaultConfig` and per-editor
+  // `editorConfig.indentUnit`, which JupyterLab registers at default precedence.
   return Prec.highest([
     indentUnit.of(resolved.unit),
     EditorState.tabSize.of(resolved.width)
@@ -86,18 +88,10 @@ function buildExtension(resolved: IResolvedIndent): Extension {
 }
 
 /**
- * Sniff each opened document's leading whitespace and configure CodeMirror's
- * `indentUnit` / `tabSize` to match. JupyterLab only exposes a single global
- * indent setting, which means TypeScript files written with 4-space indent and
- * Python files written with 2-space indent both look wrong in the same editor;
- * detecting from the file's own content sidesteps that without forcing every
- * project to share the same convention.
- *
- * Detection runs at editor-construction time and again on the first content
- * change — that second pass exists because JupyterLab's collaborative document
- * loader can settle the file body into the shared model after the editor view
- * already exists, in which case the factory would otherwise have only seen an
- * empty string.
+ * Sniff each document's indentation and configure CodeMirror's `indentUnit` /
+ * `tabSize` to match, since JupyterLab only has one global indent setting.
+ * Detection reruns on the first content change: the collaborative loader can
+ * settle the file body after the editor view exists, so the factory may see ''.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,

package/src/fileBrowser/commands.ts

@@ -32,11 +32,9 @@ import { toCanonicalPath, toServerPath } from './contents';
 import { FILE_BROWSER_ID, IXtralabFileBrowser } from './widget';
 
 /**
- * Command identifiers exposed by the xtralab browser. We deliberately namespace
- * these under `xtralab:` rather than reusing the `filebrowser:` ids
- * because the core `filebrowser:*` commands look up a `FileBrowser` instance
- * via `IFileBrowserFactory.tracker` — our widget is not a `FileBrowser`, so
- * those handlers would never see it.
+ * Command ids for the xtralab browser. Namespaced `xtralab:` rather than
+ * reusing the `filebrowser:` ids: the core handlers resolve their target via
+ * `IFileBrowserFactory.tracker`, which never sees this widget.
  */
 export namespace CommandIDs {
   export const open = 'xtralab:open';
@@ -56,27 +54,40 @@ export namespace CommandIDs {
 }
 
 /**
- * Submenu id used to host the dynamically populated "Open With" entries.
- * Distinct from the core file browser's `jp-contextmenu-open-with` so the
- * core's populator does not try to fill ours with items derived from the
- * default file browser's selection.
+ * "Open With" submenu id. Distinct from the core `jp-contextmenu-open-with`
+ * so the core's populator does not fill ours from its own selection.
  */
 const OPEN_WITH_SUBMENU_ID = 'jp-contextmenu-xtralab-open-with';
 
+/**
+ * Options for registering the xtralab file browser commands.
+ */
 interface IRegisterCommandsOptions {
+  /**
+   * The JupyterLab application the commands are registered on.
+   */
   app: JupyterFrontEnd;
+  /**
+   * The file browser widget the commands act on.
+   */
   browser: IXtralabFileBrowser;
+  /**
+   * The document manager used to resolve the current widget's file path.
+   */
   docManager: IDocumentManager;
+  /**
+   * The command palette the commands are added to, or `null` when unavailable.
+   */
   palette: ICommandPalette | null;
+  /**
+   * The translator for user-facing strings; `null` falls back to English.
+   */
   translator: ITranslator | null;
 }
 
 /**
- * Resolve the path of the item the user right-clicked. We prefer the
- * contextmenu event's target — that is how `app.contextMenu` resolves which
- * items match a selector — and fall back to the first item in the tree's
- * selection if the command was invoked without an active contextmenu event
- * (e.g. from the command palette).
+ * Path of the right-clicked item, from the contextmenu event's target;
+ * falls back to the tree selection when invoked without one (the palette).
  */
 function getTargetPath(
   app: JupyterFrontEnd,
@@ -92,11 +103,6 @@ function getTargetPath(
   return browser.selectedPaths[0];
 }
 
-/**
- * Resolve the kind of the item that was right-clicked, based on the data
- * attributes emitted by `@pierre/trees` rows. Returns `undefined` if no
- * contextmenu event is active or the target is not a tree item.
- */
 function getTargetKind(app: JupyterFrontEnd): 'file' | 'folder' | undefined {
   const node = app.contextMenuHitTest(
     n => n.dataset !== undefined && n.dataset.type === 'item'
@@ -106,14 +112,9 @@ function getTargetKind(app: JupyterFrontEnd): 'file' | 'folder' | undefined {
 }
 
 /**
- * Resolve the canonical paths the "Open" command should act on. When the
- * user right-clicks a row that is part of the current selection, every
- * selected file is opened — matching the default file browser, where
- * "Open" on any file in a multi-selection opens them all. If the
- * right-clicked row is *not* in the selection, only that row is opened.
- *
- * Folders are always filtered out: there is no "current directory" in
- * this tree, so opening a folder via "Open" is a no-op.
+ * Canonical paths "Open" acts on: the whole selection when the right-clicked
+ * row is part of it (matching the default browser), else just that row.
+ * Folders are filtered out — this tree has no "current directory".
  */
 function getOpenPaths(
   app: JupyterFrontEnd,
@@ -134,9 +135,6 @@ function getOpenPaths(
   return candidates.filter(path => !path.endsWith('/'));
 }
 
-/**
- * True iff there is an actionable target for a command on the right-click.
- */
 function hasTarget(
   app: JupyterFrontEnd,
   browser: IXtralabFileBrowser
@@ -145,11 +143,9 @@ function hasTarget(
 }
 
 /**
- * Resolve the directory used as the working directory for actions that
- * create a new file or folder. Folder selections become their own cwd;
- * file selections fall back to their parent. Returns the empty string
- * when the tree has no selection — that matches the contents API's
- * convention for "the root directory".
+ * Working directory for create actions: a selected folder is its own cwd, a
+ * file falls back to its parent; empty string (the contents-API root) when
+ * nothing is selected.
  */
 function getWorkingDirectory(browser: IXtralabFileBrowser): string {
   const first = browser.selectedPaths[0];
@@ -164,14 +160,10 @@ function getWorkingDirectory(browser: IXtralabFileBrowser): string {
 }
 
 /**
- * Resolve the main-area widget whose tab is the target of the current
- * context-menu event, or `null` when that target is not a document tab. The
- * shell stamps each tab's `data-id` with its widget id, so the right-clicked
- * tab resolves even when it is not the current one.
- *
- * Valid only during a context-menu invocation: `contextMenuHitTest` reads the
- * last context-menu event, which is not cleared when the menu closes, so
- * {@link documentPathToReveal} gates this to avoid resolving a stale tab.
+ * Main-area widget whose tab is the target of the current context-menu
+ * event, or `null`. `contextMenuHitTest` reads the last context-menu event,
+ * which is not cleared when the menu closes, so callers must gate against
+ * resolving a stale tab.
  */
 function contextMenuTabWidget(app: JupyterFrontEnd): Widget | null {
   const node = app.contextMenuHitTest(
@@ -190,10 +182,9 @@ function contextMenuTabWidget(app: JupyterFrontEnd): Widget | null {
 }
 
 /**
- * Resolve the document to reveal as a canonical `@pierre/trees` path: the
- * right-clicked tab when `fromContextMenu` is true (the file-tab menu),
- * otherwise the active main-area widget (the palette). A file's context
- * `path` is already canonical. Returns `undefined` when nothing resolves.
+ * Canonical path of the document to reveal: the right-clicked tab when
+ * `fromContextMenu` is true (the file-tab menu), else the active main-area
+ * widget (the palette).
  */
 function documentPathToReveal(
   app: JupyterFrontEnd,
@@ -211,14 +202,10 @@ function documentPathToReveal(
 }
 
 /**
- * Refresh the "Open With" submenu's items from the document factories that
- * can open the file under the right-click. Mirrors the
- * `@jupyterlab/filebrowser-extension:open-with` pattern: the schema declares
- * an empty submenu by id, and we look it up on the open context menu and
- * fill it before the user can hover.
- *
+ * Build the populator that fills the "Open With" submenu on every
+ * context-menu open, mirroring `filebrowser-extension:open-with`.
  * `preferredWidgetFactories(path)` is path-only, so the populator stays
- * synchronous and the submenu is ready before the user can hover over it.
+ * synchronous and the submenu is ready before the user can hover.
  */
 function makeOpenWithUpdater(
   app: JupyterFrontEnd,
@@ -259,13 +246,9 @@ function makeOpenWithUpdater(
 }
 
 /**
- * Register every xtralab command on the application command registry, attach
- * the items to the application context menu, and wire up the dynamic
- * "Open With" submenu populator.
- *
- * @returns A function that detaches the menu items and signal listener.
- *   The commands themselves are owned by the registry for the lifetime of
- *   the plugin.
+ * Register the xtralab commands, context-menu wiring, and the dynamic
+ * "Open With" populator. Returns a detach function; the commands themselves
+ * stay owned by the registry.
  */
 export function registerCommands(opts: IRegisterCommandsOptions): () => void {
   const { app, browser, docManager, palette, translator } = opts;
@@ -496,27 +479,33 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
     }
   });
 
-  // Refresh the toggle's state however the filter is shown or hidden —
-  // the toolbar button, or the auto-show that kicks in when typing with
-  // the tree focused opens a search session.
+  // The filter can also auto-show when typing with the tree focused, so
+  // track visibility changes rather than the command's own executions.
   const onFilterVisibleChanged = (): void => {
     commands.notifyCommandChanged(CommandIDs.toggleFileFilter);
   };
   browser.fileFilterVisibleChanged.connect(onFilterVisibleChanged);
 
-  // Public reveal seam. Other plugins (editor breadcrumbs, future
-  // "reveal in tree" actions) call this command rather than depending
-  // on the file browser widget directly. Activating the sidebar is part
-  // of the contract: the tree is hidden behind a tab and a reveal that
-  // does not surface the panel would silently no-op from the user's
-  // point of view. An empty path is the "workspace root" gesture —
-  // there is no tree row for the root itself, so the browser is asked
-  // to scroll back to the top and clear its selection instead.
+  // Public reveal seam for other plugins; an empty path is the workspace-root
+  // gesture (the root has no tree row of its own). The tree is movable, so
+  // surface whichever sidebar widget holds it.
+  const activateTreeHost = (): void => {
+    for (const area of ['left', 'right']) {
+      for (const widget of app.shell.widgets(area)) {
+        if (widget.node.contains(browser.sectionNode)) {
+          app.shell.activateById(widget.id);
+          return;
+        }
+      }
+    }
+    app.shell.activateById(FILE_BROWSER_ID);
+  };
+
   commands.addCommand(CommandIDs.revealPath, {
     label: trans.__('Reveal in File Browser'),
     execute: (args: ReadonlyPartialJSONObject) => {
       const path = (args.path as string | undefined) ?? '';
-      app.shell.activateById(FILE_BROWSER_ID);
+      activateTreeHost();
       if (path.length === 0) {
         browser.scrollToRoot();
       } else {
@@ -525,8 +514,6 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
     }
   });
 
-  // Reveal the resolved document in the tree browser via the reveal-path
-  // command, which surfaces the sidebar and scrolls to the target.
   commands.addCommand(CommandIDs.revealInFileTree, {
     label: trans.__('Show in File Tree'),
     caption: trans.__('Show this file in the xtralab file browser'),
@@ -566,10 +553,8 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
   commands.addCommand(CommandIDs.newLauncher, {
     label: trans.__('New Launcher'),
     caption: trans.__('Open a new launcher'),
-    // Skip the `menuItem` bindprops the other commands use: this command
-    // lives on the toolbar, where the launcher-extension's blue button
-    // styling expects the raw `jp-icon3` paths from `addIcon` so it can
-    // recolor them against the brand background.
+    // Raw `addIcon`, no `menuItem` bindprops: the launcher-extension's blue
+    // toolbar-button styling recolors the raw `jp-icon3` paths.
     icon: addIcon,
     execute: () => {
       const cwd = getWorkingDirectory(browser);
@@ -577,34 +562,24 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
     }
   });
 
-  // Re-evaluate enabled/visible state when the user changes the tree
-  // selection, in case a command's predicate depends on the selection.
   browser.selectionChanged.connect(() => {
     for (const id of Object.values(CommandIDs)) {
       commands.notifyCommandChanged(id);
     }
   });
 
-  // This command's enabled state tracks the active widget, not the tree
-  // selection, so re-evaluate it on current-widget changes. `currentChanged`
-  // is optional on the shell interface.
   const onCurrentChanged = (): void => {
     commands.notifyCommandChanged(CommandIDs.revealInFileTree);
   };
   app.shell.currentChanged?.connect(onCurrentChanged);
 
-  // Also surface it in the palette (acts on the active editor); the file-tab
-  // context-menu entry is declared in `schema/plugin.json`.
   const paletteItem = palette?.addItem({
     command: CommandIDs.revealInFileTree,
     category: trans.__('File Browser')
   });
 
-  // The static items are declared in `schema/plugin.json` under
-  // `jupyter.lab.menus.context` so users can override or disable them. The
-  // schema also declares an empty submenu placeholder with id
-  // `OPEN_WITH_SUBMENU_ID`; we fill it on every open from the document
-  // factories that can open the right-clicked file.
+  // Static context-menu items live in `schema/plugin.json` so users can
+  // override them; the schema declares the empty "Open With" placeholder.
   const updateOpenWithMenu = makeOpenWithUpdater(app, browser);
   app.contextMenu.opened.connect(updateOpenWithMenu);
 
@@ -617,9 +592,8 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
 }
 
 /**
- * The names we register with the toolbar. Kept distinct from
- * {@link CommandIDs} because the toolbar API uses opaque names rather
- * than commands.
+ * Toolbar item names, distinct from {@link CommandIDs}: the toolbar API
+ * uses opaque names rather than commands.
  */
 export namespace ToolbarNames {
   export const newLauncher = 'new-launcher';
@@ -630,10 +604,8 @@ export namespace ToolbarNames {
 }
 
 /**
- * Populate the file browser's toolbar with the buttons that mirror the
- * default JupyterLab file browser: a "+" launcher button, a new-folder
- * button, a refresh button, a collapse-all button, and the file filter
- * toggle.
+ * Populate the toolbar with the buttons that mirror the default JupyterLab
+ * file browser.
  */
 export function populateToolbar(opts: {
   app: JupyterFrontEnd;