xtralab 0.11.0 → 0.12.0

package/lib/omnibox/index.js

@@ -1,7 +1,10 @@
 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';
 const PLUGIN_ID = 'xtralab:omnibox';
@@ -12,6 +15,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.
  */
@@ -20,11 +27,44 @@ const plugin = {
     description: 'A launcher overlay that searches files and commands and prompts agents.',
     autoStart: true,
     provides: IOmnibox,
-    optional: [IAgentRegistry, ICommandPalette, ITranslator],
-    activate: (app, agentRegistry, palette, translator) => {
+    optional: [
+        IAgentRegistry,
+        ICommandPalette,
+        ISettingRegistry,
+        IStateDB,
+        ITranslator
+    ],
+    activate: (app, agentRegistry, palette, settingRegistry, state, translator) => {
         const { commands, docRegistry } = app;
         const trans = (translator !== null && translator !== void 0 ? 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 = () => {
+                    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 = null;
         const close = () => {
             const widget = current;
@@ -41,6 +81,7 @@ const plugin = {
                 agents: agentRegistry ? agentRegistry.agents : [],
                 placeholder,
                 initialQuery: query !== null && query !== void 0 ? query : '',
+                recents,
                 trans,
                 onClose: close
             });

package/lib/omnibox/model.d.ts

@@ -3,43 +3,72 @@ import type { TranslationBundle } from '@jupyterlab/translation';
 import { LabIcon } from '@jupyterlab/ui-components';
 import type { CommandRegistry } from '@lumino/commands';
 import type { IAgent } from '../launcher/agents';
-/** The source a result row came from, used to group rows under a header. */
-export type OmniboxItemKind = 'command' | 'file' | 'agent';
-/** A single result row, with the action it runs when chosen. */
+import type { OmniboxRecents } from './recents';
+/**
+ * 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;
 }
 /**
  * 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 declare function computeSections(options: IComputeOptions): IOmniboxSections;
+export {};

package/lib/omnibox/model.js

@@ -14,11 +14,12 @@ const FILE_PREFIX = '/';
  * 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) {
-    const { query, commands, docRegistry, agents, files, trans } = options;
+    const { query, commands, agents, trans } = options;
     const trimmed = query.trim();
     let mode = 'all';
     let term = trimmed;
@@ -31,16 +32,121 @@ export function computeSections(options) {
         term = trimmed.slice(FILE_PREFIX.length).trim();
     }
     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(commands, term) {
+/**
+ * Run a command and record the use on success, so failed commands never enter
+ * the recents list.
+ */
+function executeCommand(commands, recents, id) {
+    void commands
+        .execute(id)
+        .then(() => {
+        recents === null || recents === void 0 ? void 0 : 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, recents, path) {
+    void commands
+        .execute('docmanager:open', { path })
+        .then(() => {
+        recents === null || recents === void 0 ? void 0 : 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, id) {
+    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 (_a) {
+        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, mode) {
+    const { commands, docRegistry, files, recents } = options;
+    if (!recents) {
+        return [];
+    }
+    const kind = mode === 'commands' ? 'command' : mode === 'files' ? 'file' : undefined;
+    const knownFiles = files.length > 0 ? new Set(files) : null;
+    const items = [];
+    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, term) {
+    const { commands, recents } = options;
     const query = term.toLowerCase();
     const scored = [];
     for (const id of commands.listCommands()) {
@@ -73,9 +179,7 @@ function matchCommands(commands, term) {
                 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);
                 }
             }
         });
@@ -83,7 +187,8 @@ function matchCommands(commands, term) {
     scored.sort((a, b) => a.score - b.score);
     return scored.slice(0, COMMAND_LIMIT).map(entry => entry.item);
 }
-function matchFiles(commands, docRegistry, files, term) {
+function matchFiles(options, term) {
+    const { commands, docRegistry, files, recents } = options;
     const query = term.toLowerCase();
     const scored = [];
     for (const path of files) {
@@ -100,9 +205,7 @@ function matchFiles(commands, docRegistry, files, term) {
         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/lib/omnibox/recents.d.ts

@@ -0,0 +1,65 @@
+import type { IStateDB } from '@jupyterlab/statedb';
+/**
+ * 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;
+}
+/**
+ * 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 declare class OmniboxRecents {
+    constructor(options?: OmniboxRecents.IOptions);
+    /**
+     * Maximum number of entries remembered per kind. Lowering it trims the list
+     * immediately; `0` disables recents entirely.
+     */
+    get maxItems(): number;
+    set maxItems(value: number);
+    /**
+     * The recorded entries, most recent first — all of them, or only those of
+     * one kind.
+     */
+    entries(kind?: RecentKind): IRecentEntry[];
+    /**
+     * Record a use of `id`, moving it to the front of its kind's list.
+     */
+    touch(kind: RecentKind, id: string): void;
+    /**
+     * Load the persisted list. Entries recorded before the load completes stay
+     * at the front, ahead of the restored history.
+     */
+    restore(): Promise<void>;
+    /**
+     * Keep at most `maxItems` entries of each kind, preserving order.
+     */
+    private _trim;
+    private _save;
+    private _state;
+    private _entries;
+    private _maxItems;
+}
+export declare namespace OmniboxRecents {
+    /**
+     * Construction options for {@link OmniboxRecents}.
+     */
+    interface IOptions {
+        /**
+         * The state database to persist through, if available.
+         */
+        state?: IStateDB | null;
+    }
+}
+export {};

package/lib/omnibox/recents.js

@@ -0,0 +1,109 @@
+/**
+ * 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 = {}) {
+        var _a;
+        this._entries = [];
+        this._maxItems = 5;
+        this._state = (_a = options.state) !== null && _a !== void 0 ? _a : null;
+    }
+    /**
+     * Maximum number of entries remembered per kind. Lowering it trims the list
+     * immediately; `0` disables recents entirely.
+     */
+    get maxItems() {
+        return this._maxItems;
+    }
+    set maxItems(value) {
+        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) {
+        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, id) {
+        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() {
+        if (!this._state) {
+            return;
+        }
+        let fetched;
+        try {
+            fetched = await this._state.fetch(STATE_KEY);
+        }
+        catch (_a) {
+            return;
+        }
+        const persisted = Array.isArray(fetched)
+            ? fetched.filter((entry) => !!entry &&
+                typeof entry === 'object' &&
+                (entry.kind === 'command' ||
+                    entry.kind === 'file') &&
+                typeof entry.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.
+     */
+    _trim(entries) {
+        const counts = new Map();
+        return entries.filter(entry => {
+            var _a;
+            const count = (_a = counts.get(entry.kind)) !== null && _a !== void 0 ? _a : 0;
+            counts.set(entry.kind, count + 1);
+            return count < this._maxItems;
+        });
+    }
+    _save() {
+        if (!this._state) {
+            return;
+        }
+        const value = this._entries.map(entry => ({
+            kind: entry.kind,
+            id: entry.id
+        }));
+        this._state.save(STATE_KEY, value).catch(reason => {
+            console.error('xtralab omnibox: failed to save recents', reason);
+        });
+    }
+}

package/lib/omnibox/tokens.d.ts

@@ -6,9 +6,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/lib/omnibox/widget.d.ts

@@ -3,6 +3,7 @@ import type { TranslationBundle } from '@jupyterlab/translation';
 import { ReactWidget } from '@jupyterlab/ui-components';
 import type { CommandRegistry } from '@lumino/commands';
 import type { IAgent } from '../launcher/agents';
+import type { OmniboxRecents } from './recents';
 /**
  * The omnibox overlay widget. Hosts {@link OmniboxComponent} in a React root
  * attached to `document.body`. It carries `jp-ThemedContainer` so JupyterLab's
@@ -18,19 +19,35 @@ export declare class OmniboxWidget extends ReactWidget {
  * A namespace for `OmniboxWidget` statics.
  */
 export declare namespace OmniboxWidget {
-    /** Construction options for {@link OmniboxWidget}. */
+    /**
+     * Construction options for {@link OmniboxWidget}.
+     */
     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;
     }
 }

package/lib/omnibox/widget.js

@@ -2,9 +2,13 @@ import { ReactWidget } from '@jupyterlab/ui-components';
 import * as React from 'react';
 import { computeSections } from './model';
 import { loadWorkspaceFiles } from './files';
-/** 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) {
     return `jp-xtralab-Omnibox-option-${index}`;
 }
@@ -35,7 +39,7 @@ function renderIcon(icon) {
     return icon ? (React.createElement(icon.react, { tag: "span", className: "jp-xtralab-Omnibox-itemIcon" })) : (React.createElement("span", { className: "jp-xtralab-Omnibox-itemIcon" }));
 }
 function OmniboxComponent(props) {
-    const { commands, docRegistry, agents, placeholder, initialQuery, trans, onClose } = props;
+    const { commands, docRegistry, agents, placeholder, initialQuery, recents, trans, onClose } = props;
     const [query, setQuery] = React.useState(initialQuery);
     const [files, setFiles] = React.useState([]);
     const [active, setActive] = React.useState(0);
@@ -56,8 +60,21 @@ function OmniboxComponent(props) {
             cancelled = true;
         };
     }, []);
-    const sections = React.useMemo(() => computeSections({ query, commands, docRegistry, agents, files, trans }), [query, commands, docRegistry, agents, files, trans]);
-    const flat = React.useMemo(() => [...sections.commands, ...sections.files, ...sections.agents], [sections]);
+    const sections = React.useMemo(() => computeSections({
+        query,
+        commands,
+        docRegistry,
+        agents,
+        files,
+        recents,
+        trans
+    }), [query, commands, docRegistry, agents, files, recents, trans]);
+    const flat = React.useMemo(() => [
+        ...sections.recent,
+        ...sections.commands,
+        ...sections.files,
+        ...sections.agents
+    ], [sections]);
     const hasResults = flat.length > 0;
     // Reset the highlighted row whenever the result set changes, and keep the
     // index in range when results shrink.
@@ -125,7 +142,8 @@ function OmniboxComponent(props) {
                     item.caption ? (React.createElement("span", { className: "jp-xtralab-Omnibox-itemCaption" }, item.caption)) : null));
             })));
     };
-    const filesStart = sections.commands.length;
+    const commandsStart = sections.recent.length;
+    const filesStart = commandsStart + sections.commands.length;
     const agentsStart = filesStart + sections.files.length;
     return (React.createElement("div", { className: "jp-xtralab-Omnibox-overlay", onMouseDown: event => {
             if (event.target === event.currentTarget) {
@@ -135,7 +153,8 @@ function OmniboxComponent(props) {
         React.createElement("div", { className: "jp-xtralab-Omnibox-panel", role: "dialog", "aria-modal": "true", "aria-label": placeholder, onMouseDown: event => event.stopPropagation() },
             React.createElement("input", { ref: inputRef, className: "jp-xtralab-Omnibox-input", type: "text", spellCheck: false, placeholder: placeholder, "aria-label": placeholder, role: "combobox", "aria-autocomplete": "list", "aria-expanded": hasResults, "aria-controls": LIST_ID, "aria-activedescendant": hasResults ? optionId(active) : undefined, value: query, onChange: event => setQuery(event.target.value), onKeyDown: onKeyDown }),
             React.createElement("div", { className: "jp-xtralab-Omnibox-results", id: LIST_ID, role: hasResults ? 'listbox' : undefined, ref: listRef }, hasResults ? (React.createElement(React.Fragment, null,
-                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'), sections.agents, agentsStart))) : (React.createElement("div", { className: "jp-xtralab-Omnibox-empty" }, query.trim()
                 ? trans.__('No matches.')