xtralab 0.11.0 → 0.12.0

package/src/omnibox/index.ts

@@ -3,11 +3,14 @@ import {
   JupyterFrontEndPlugin
 } from '@jupyterlab/application';
 import { ICommandPalette } from '@jupyterlab/apputils';
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { IStateDB } from '@jupyterlab/statedb';
 import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 import { Widget } from '@lumino/widgets';
 
 import { IAgentRegistry } from '../launcher/tokens';
 
+import { OmniboxRecents } from './recents';
 import { IOmnibox, OMNIBOX_OPEN_COMMAND } from './tokens';
 import { OmniboxWidget } from './widget';
 
@@ -20,6 +23,10 @@ const PLUGIN_ID = 'xtralab:omnibox';
  * it in a fresh terminal through the launcher's `xtralab:start-agent:<id>`
  * commands). It is opened by the top-bar command bar.
  *
+ * Commands run and files opened through the overlay are remembered (persisted
+ * in the state database) and offered again at the top while the query is
+ * empty; the `maxNumberRecents` setting caps how many of each are kept.
+ *
  * The agent rows come from the launcher's `IAgentRegistry`; when the launcher
  * is disabled the omnibox still searches files and commands.
  */
@@ -29,17 +36,56 @@ const plugin: JupyterFrontEndPlugin<IOmnibox> = {
     'A launcher overlay that searches files and commands and prompts agents.',
   autoStart: true,
   provides: IOmnibox,
-  optional: [IAgentRegistry, ICommandPalette, ITranslator],
+  optional: [
+    IAgentRegistry,
+    ICommandPalette,
+    ISettingRegistry,
+    IStateDB,
+    ITranslator
+  ],
   activate: (
     app: JupyterFrontEnd,
     agentRegistry: IAgentRegistry | null,
     palette: ICommandPalette | null,
+    settingRegistry: ISettingRegistry | null,
+    state: IStateDB | null,
     translator: ITranslator | null
   ): IOmnibox => {
     const { commands, docRegistry } = app;
     const trans = (translator ?? nullTranslator).load('jupyterlab');
     const placeholder = trans.__('Search files and commands, or ask an agent…');
 
+    const recents = new OmniboxRecents({ state });
+
+    // Restore the persisted recents only after the configured cap is known:
+    // `restore` trims to `maxItems`, so restoring at the constructor default
+    // would permanently drop entries beyond it whenever the user configured a
+    // larger cap and the state fetch won the race against the settings load.
+    if (settingRegistry) {
+      void settingRegistry
+        .load(PLUGIN_ID)
+        .then(settings => {
+          const apply = (): void => {
+            const value = settings.get('maxNumberRecents').composite;
+            if (typeof value === 'number') {
+              recents.maxItems = value;
+            }
+          };
+          apply();
+          settings.changed.connect(apply);
+          void recents.restore();
+        })
+        .catch(reason => {
+          console.error(
+            `xtralab omnibox: failed to load settings for ${PLUGIN_ID}`,
+            reason
+          );
+          void recents.restore();
+        });
+    } else {
+      void recents.restore();
+    }
+
     let current: OmniboxWidget | null = null;
 
     const close = (): void => {
@@ -58,6 +104,7 @@ const plugin: JupyterFrontEndPlugin<IOmnibox> = {
         agents: agentRegistry ? agentRegistry.agents : [],
         placeholder,
         initialQuery: query ?? '',
+        recents,
         trans,
         onClose: close
       });

package/src/omnibox/model.ts

@@ -7,39 +7,67 @@ import type { CommandRegistry } from '@lumino/commands';
 import type { IAgent } from '../launcher/agents';
 import { agentCommandId } from '../launcher/tokens';
 
-/** The source a result row came from, used to group rows under a header. */
-export type OmniboxItemKind = 'command' | 'file' | 'agent';
+import type { OmniboxRecents, RecentKind } from './recents';
 
-/** A single result row, with the action it runs when chosen. */
+/**
+ * The source a result row came from, used to group rows under a header.
+ */
+type OmniboxItemKind = 'command' | 'file' | 'agent';
+
+/**
+ * A single result row, with the action it runs when chosen.
+ */
 export interface IOmniboxItem {
   kind: OmniboxItemKind;
-  /** Stable React key. */
+  /**
+   * Stable React key.
+   */
   key: string;
-  /** Primary text shown on the row. */
+  /**
+   * Primary text shown on the row.
+   */
   label: string;
-  /** Indices of matched characters in `label`, for highlighting. May be empty. */
+  /**
+   * Indices of matched characters in `label`, for highlighting. May be empty.
+   */
   matchIndices: readonly number[];
-  /** Optional secondary text shown trailing the label. */
+  /**
+   * Optional secondary text shown trailing the label.
+   */
   caption?: string;
-  /** Optional leading icon. */
+  /**
+   * Optional leading icon.
+   */
   icon?: LabIcon;
-  /** Run the row's action. */
+  /**
+   * Run the row's action.
+   */
   execute: () => void;
 }
 
-/** Results grouped by source; each group is already capped and sorted. */
-export interface IOmniboxSections {
+/**
+ * Results grouped by source; each group is already capped and sorted.
+ */
+interface IOmniboxSections {
+  /**
+   * Recently used commands and files, shown while the term is empty.
+   */
+  recent: IOmniboxItem[];
   commands: IOmniboxItem[];
   files: IOmniboxItem[];
   agents: IOmniboxItem[];
 }
 
-export interface IComputeOptions {
+interface IComputeOptions {
   query: string;
   commands: CommandRegistry;
   docRegistry: DocumentRegistry;
   agents: IAgent[];
   files: string[];
+  /**
+   * Recently-used tracker; `null` disables the recent rows and recording.
+   */
+  recents: OmniboxRecents | null;
   trans: TranslationBundle;
 }
 
@@ -60,11 +88,12 @@ type Mode = 'all' | 'commands' | 'files';
  * Build the grouped result set for a query. A leading `>` searches only
  * commands and a leading `/` only files; otherwise commands and files are
  * fuzzy-matched and every prompt-capable agent is offered an "Ask" row
- * carrying the query as its prompt. An empty term yields no rows (the widget
- * shows a hint instead).
+ * carrying the query as its prompt. An empty term yields the recently used
+ * rows for the active mode instead (and the widget shows a hint when there
+ * are none).
  */
 export function computeSections(options: IComputeOptions): IOmniboxSections {
-  const { query, commands, docRegistry, agents, files, trans } = options;
+  const { query, commands, agents, trans } = options;
   const trimmed = query.trim();
 
   let mode: Mode = 'all';
@@ -78,22 +107,141 @@ export function computeSections(options: IComputeOptions): IOmniboxSections {
   }
 
   if (!term) {
-    return { commands: [], files: [], agents: [] };
+    return {
+      recent: buildRecentItems(options, mode),
+      commands: [],
+      files: [],
+      agents: []
+    };
   }
 
   return {
-    commands: mode === 'files' ? [] : matchCommands(commands, term),
-    files:
-      mode === 'commands' ? [] : matchFiles(commands, docRegistry, files, term),
+    recent: [],
+    commands: mode === 'files' ? [] : matchCommands(options, term),
+    files: mode === 'commands' ? [] : matchFiles(options, term),
     // Agents only in the unprefixed view; the prompt is the full typed query.
     agents: mode === 'all' ? buildAgentItems(commands, agents, term, trans) : []
   };
 }
 
-function matchCommands(
+/**
+ * Run a command and record the use on success, so failed commands never enter
+ * the recents list.
+ */
+function executeCommand(
   commands: CommandRegistry,
-  term: string
+  recents: OmniboxRecents | null,
+  id: string
+): void {
+  void commands
+    .execute(id)
+    .then(() => {
+      recents?.touch('command', id);
+    })
+    .catch(reason => {
+      console.error(`xtralab omnibox: command "${id}" failed`, reason);
+    });
+}
+
+/**
+ * Open a file and record the use on success.
+ */
+function openFile(
+  commands: CommandRegistry,
+  recents: OmniboxRecents | null,
+  path: string
+): void {
+  void commands
+    .execute('docmanager:open', { path })
+    .then(() => {
+      recents?.touch('file', path);
+    })
+    .catch(reason => {
+      console.error(`xtralab omnibox: failed to open "${path}"`, reason);
+    });
+}
+
+/**
+ * Read a command's label, visibility and caption, or `null` when the command
+ * is missing, hidden, label-less, or its accessors throw (a command's
+ * accessors can assume a context — e.g. an active notebook — the omnibox
+ * doesn't provide).
+ */
+function commandDisplay(
+  commands: CommandRegistry,
+  id: string
+): { label: string; caption: string } | null {
+  if (!commands.hasCommand(id)) {
+    return null;
+  }
+  try {
+    const label = commands.label(id);
+    if (!label || !commands.isVisible(id)) {
+      return null;
+    }
+    return { label, caption: commands.caption(id) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The recently used rows for the empty term: both kinds interleaved by
+ * recency in the unprefixed view, or only the mode's kind under a bare `>` or
+ * `/`. Commands that no longer resolve are dropped, as are files missing from
+ * the loaded workspace listing (while the listing is still loading — or
+ * unavailable — file entries are shown as recorded).
+ */
+function buildRecentItems(
+  options: IComputeOptions,
+  mode: Mode
 ): IOmniboxItem[] {
+  const { commands, docRegistry, files, recents } = options;
+  if (!recents) {
+    return [];
+  }
+  const kind: RecentKind | undefined =
+    mode === 'commands' ? 'command' : mode === 'files' ? 'file' : undefined;
+  const knownFiles = files.length > 0 ? new Set(files) : null;
+
+  const items: IOmniboxItem[] = [];
+  for (const entry of recents.entries(kind)) {
+    if (entry.kind === 'command') {
+      const display = commandDisplay(commands, entry.id);
+      if (!display) {
+        continue;
+      }
+      items.push({
+        kind: 'command',
+        key: `recent:command:${entry.id}`,
+        label: display.label,
+        matchIndices: [],
+        caption: display.caption || undefined,
+        execute: () => {
+          executeCommand(commands, recents, entry.id);
+        }
+      });
+    } else {
+      if (knownFiles && !knownFiles.has(entry.id)) {
+        continue;
+      }
+      items.push({
+        kind: 'file',
+        key: `recent:file:${entry.id}`,
+        label: entry.id,
+        matchIndices: [],
+        icon: fileIconForPath(docRegistry, entry.id),
+        execute: () => {
+          openFile(commands, recents, entry.id);
+        }
+      });
+    }
+  }
+  return items;
+}
+
+function matchCommands(options: IComputeOptions, term: string): IOmniboxItem[] {
+  const { commands, recents } = options;
   const query = term.toLowerCase();
   const scored: Array<{ score: number; item: IOmniboxItem }> = [];
   for (const id of commands.listCommands()) {
@@ -125,9 +273,7 @@ function matchCommands(
         matchIndices: match.indices,
         caption: caption || undefined,
         execute: () => {
-          void commands.execute(id).catch(reason => {
-            console.error(`xtralab omnibox: command "${id}" failed`, reason);
-          });
+          executeCommand(commands, recents, id);
         }
       }
     });
@@ -136,12 +282,8 @@ function matchCommands(
   return scored.slice(0, COMMAND_LIMIT).map(entry => entry.item);
 }
 
-function matchFiles(
-  commands: CommandRegistry,
-  docRegistry: DocumentRegistry,
-  files: string[],
-  term: string
-): IOmniboxItem[] {
+function matchFiles(options: IComputeOptions, term: string): IOmniboxItem[] {
+  const { commands, docRegistry, files, recents } = options;
   const query = term.toLowerCase();
   const scored: Array<{ score: number; path: string; indices: number[] }> = [];
   for (const path of files) {
@@ -158,9 +300,7 @@ function matchFiles(
     matchIndices: indices,
     icon: fileIconForPath(docRegistry, path),
     execute: () => {
-      void commands.execute('docmanager:open', { path }).catch(reason => {
-        console.error(`xtralab omnibox: failed to open "${path}"`, reason);
-      });
+      openFile(commands, recents, path);
     }
   }));
 }

package/src/omnibox/recents.ts

@@ -0,0 +1,155 @@
+import type { IStateDB } from '@jupyterlab/statedb';
+import type { PartialJSONObject } from '@lumino/coreutils';
+
+/**
+ * Kinds of omnibox results whose uses are recorded.
+ */
+export type RecentKind = 'command' | 'file';
+
+/**
+ * A single recorded use: a command that was run or a file that was opened.
+ */
+interface IRecentEntry {
+  kind: RecentKind;
+  /**
+   * The command id, or the workspace-relative file path.
+   */
+  id: string;
+}
+
+/**
+ * State database key the recents list is persisted under.
+ */
+const STATE_KEY = 'xtralab:omnibox:recents';
+
+/**
+ * A most-recently-used list of omnibox results, generic over the result kind
+ * so commands and files (and future kinds) share one store. Entries are kept
+ * most-recent-first, capped at `maxItems` per kind, and persisted through the
+ * state database so they survive reloads. Without a state database the list
+ * still works for the lifetime of the page.
+ */
+export class OmniboxRecents {
+  constructor(options: OmniboxRecents.IOptions = {}) {
+    this._state = options.state ?? null;
+  }
+
+  /**
+   * Maximum number of entries remembered per kind. Lowering it trims the list
+   * immediately; `0` disables recents entirely.
+   */
+  get maxItems(): number {
+    return this._maxItems;
+  }
+  set maxItems(value: number) {
+    const normalized = Math.max(0, Math.floor(value));
+    if (normalized === this._maxItems) {
+      return;
+    }
+    this._maxItems = normalized;
+    const trimmed = this._trim(this._entries);
+    if (trimmed.length !== this._entries.length) {
+      this._entries = trimmed;
+      this._save();
+    }
+  }
+
+  /**
+   * The recorded entries, most recent first — all of them, or only those of
+   * one kind.
+   */
+  entries(kind?: RecentKind): IRecentEntry[] {
+    return kind
+      ? this._entries.filter(entry => entry.kind === kind)
+      : [...this._entries];
+  }
+
+  /**
+   * Record a use of `id`, moving it to the front of its kind's list.
+   */
+  touch(kind: RecentKind, id: string): void {
+    const rest = this._entries.filter(
+      entry => !(entry.kind === kind && entry.id === id)
+    );
+    this._entries = this._trim([{ kind, id }, ...rest]);
+    this._save();
+  }
+
+  /**
+   * Load the persisted list. Entries recorded before the load completes stay
+   * at the front, ahead of the restored history.
+   */
+  async restore(): Promise<void> {
+    if (!this._state) {
+      return;
+    }
+    let fetched: unknown;
+    try {
+      fetched = await this._state.fetch(STATE_KEY);
+    } catch {
+      return;
+    }
+    const persisted: IRecentEntry[] = Array.isArray(fetched)
+      ? fetched.filter(
+          (entry): entry is IRecentEntry =>
+            !!entry &&
+            typeof entry === 'object' &&
+            ((entry as IRecentEntry).kind === 'command' ||
+              (entry as IRecentEntry).kind === 'file') &&
+            typeof (entry as IRecentEntry).id === 'string'
+        )
+      : [];
+    const merged = [...this._entries];
+    for (const entry of persisted) {
+      if (
+        !merged.some(
+          existing => existing.kind === entry.kind && existing.id === entry.id
+        )
+      ) {
+        merged.push({ kind: entry.kind, id: entry.id });
+      }
+    }
+    this._entries = this._trim(merged);
+  }
+
+  /**
+   * Keep at most `maxItems` entries of each kind, preserving order.
+   */
+  private _trim(entries: IRecentEntry[]): IRecentEntry[] {
+    const counts = new Map<RecentKind, number>();
+    return entries.filter(entry => {
+      const count = counts.get(entry.kind) ?? 0;
+      counts.set(entry.kind, count + 1);
+      return count < this._maxItems;
+    });
+  }
+
+  private _save(): void {
+    if (!this._state) {
+      return;
+    }
+    const value = this._entries.map<PartialJSONObject>(entry => ({
+      kind: entry.kind,
+      id: entry.id
+    }));
+    this._state.save(STATE_KEY, value).catch(reason => {
+      console.error('xtralab omnibox: failed to save recents', reason);
+    });
+  }
+
+  private _state: IStateDB | null;
+  private _entries: IRecentEntry[] = [];
+  private _maxItems = 5;
+}
+
+export namespace OmniboxRecents {
+  /**
+   * Construction options for {@link OmniboxRecents}.
+   */
+  export interface IOptions {
+    /**
+     * The state database to persist through, if available.
+     */
+    state?: IStateDB | null;
+  }
+}

package/src/omnibox/tokens.ts

@@ -7,9 +7,13 @@ import { Token } from '@lumino/coreutils';
  * by the top-bar command bar, which opens it on click.
  */
 export interface IOmnibox {
-  /** Open the overlay, optionally seeding the input with `query`. */
+  /**
+   * Open the overlay, optionally seeding the input with `query`.
+   */
   open(query?: string): void;
-  /** Close the overlay if it is open. */
+  /**
+   * Close the overlay if it is open.
+   */
   close(): void;
 }
 

package/src/omnibox/widget.tsx

@@ -8,11 +8,16 @@ import type { IAgent } from '../launcher/agents';
 
 import { computeSections, IOmniboxItem } from './model';
 import { loadWorkspaceFiles } from './files';
+import type { OmniboxRecents } from './recents';
 
-/** DOM id of the results listbox, referenced by the input's `aria-controls`. */
+/**
+ * DOM id of the results listbox, referenced by the input's `aria-controls`.
+ */
 const LIST_ID = 'jp-xtralab-Omnibox-list';
 
-/** Stable DOM id for the result row at `index`, for `aria-activedescendant`. */
+/**
+ * Stable DOM id for the result row at `index`, for `aria-activedescendant`.
+ */
 function optionId(index: number): string {
   return `jp-xtralab-Omnibox-option-${index}`;
 }
@@ -67,6 +72,7 @@ function OmniboxComponent(props: OmniboxWidget.IOptions): JSX.Element {
     agents,
     placeholder,
     initialQuery,
+    recents,
     trans,
     onClose
   } = props;
@@ -94,11 +100,24 @@ function OmniboxComponent(props: OmniboxWidget.IOptions): JSX.Element {
 
   const sections = React.useMemo(
     () =>
-      computeSections({ query, commands, docRegistry, agents, files, trans }),
-    [query, commands, docRegistry, agents, files, trans]
+      computeSections({
+        query,
+        commands,
+        docRegistry,
+        agents,
+        files,
+        recents,
+        trans
+      }),
+    [query, commands, docRegistry, agents, files, recents, trans]
   );
   const flat = React.useMemo(
-    () => [...sections.commands, ...sections.files, ...sections.agents],
+    () => [
+      ...sections.recent,
+      ...sections.commands,
+      ...sections.files,
+      ...sections.agents
+    ],
     [sections]
   );
   const hasResults = flat.length > 0;
@@ -212,7 +231,8 @@ function OmniboxComponent(props: OmniboxWidget.IOptions): JSX.Element {
     );
   };
 
-  const filesStart = sections.commands.length;
+  const commandsStart = sections.recent.length;
+  const filesStart = commandsStart + sections.commands.length;
   const agentsStart = filesStart + sections.files.length;
 
   return (
@@ -255,7 +275,12 @@ function OmniboxComponent(props: OmniboxWidget.IOptions): JSX.Element {
         >
           {hasResults ? (
             <>
-              {renderSection(trans.__('Commands'), sections.commands, 0)}
+              {renderSection(trans.__('Recently used'), sections.recent, 0)}
+              {renderSection(
+                trans.__('Commands'),
+                sections.commands,
+                commandsStart
+              )}
               {renderSection(trans.__('Files'), sections.files, filesStart)}
               {renderSection(
                 trans.__('Ask an agent'),
@@ -304,19 +329,35 @@ export class OmniboxWidget extends ReactWidget {
  * A namespace for `OmniboxWidget` statics.
  */
 export namespace OmniboxWidget {
-  /** Construction options for {@link OmniboxWidget}. */
+  /**
+   * Construction options for {@link OmniboxWidget}.
+   */
   export interface IOptions {
     commands: CommandRegistry;
     docRegistry: DocumentRegistry;
-    /** Snapshot of the available agents, read once when the overlay opens. */
+    /**
+     * Snapshot of the available agents, read once when the overlay opens.
+     */
     agents: IAgent[];
-    /** Placeholder text for the input. */
+    /**
+     * Placeholder text for the input.
+     */
     placeholder: string;
-    /** Seed text for the input. */
+    /**
+     * Seed text for the input.
+     */
     initialQuery: string;
-    /** Translation bundle for the overlay's own labels. */
+    /**
+     * Recently-used tracker; `null` disables the recent rows and recording.
+     */
+    recents: OmniboxRecents | null;
+    /**
+     * Translation bundle for the overlay's own labels.
+     */
     trans: TranslationBundle;
-    /** Dismiss the overlay (the plugin disposes the widget). */
+    /**
+     * Dismiss the overlay (the plugin disposes the widget).
+     */
     onClose: () => void;
   }
 }