@oceanum/oceanumlab 4.7.0 → 4.7.2

package/lib/share/oceanumOnly.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Oceanum-only file management: what a deployment gets when its environment says
+ * `fileManagement: 'oceanum'`, as notebook.oceanum.io does.
+ *
+ * The local drive stays as the working copy underneath, out of sight: the file browser
+ * is taken out of the sidebar, the File menu loses the entries that manage local files,
+ * and every completed local save is pushed to the spec store, so Ctrl+S, the toolbar
+ * button, Save All and autosave all reach Oceanum.
+ */
+import type { INotebookTracker, NotebookPanel } from '@jupyterlab/notebook';
+import type { Menu, Widget } from '@lumino/widgets';
+/** The widget id `@jupyterlab/filebrowser-extension:browser` gives the file browser. */
+export declare const FILE_BROWSER_ID = "filebrowser";
+/**
+ * File menu entries that manage local files. Save, Save All and Rename stay: saving is
+ * routed to Oceanum, and renaming the local file is how a notebook gets its name.
+ */
+export declare const LOCAL_FILE_COMMANDS: readonly string[];
+/**
+ * Take the file browser out of the sidebar; true if it was there. It is closed, not
+ * disposed: other extensions hold it through IDefaultFileBrowser and still use it to
+ * open paths.
+ */
+export declare function hideFileBrowser(shell: {
+    widgets(area: 'left'): Iterable<Widget>;
+}): boolean;
+/**
+ * Submenus of local files. "Open Recent" is built by the document manager rather than
+ * declared in a schema, and its menu has no id, so it is known by the commands it holds.
+ */
+export declare const LOCAL_FILE_SUBMENU_COMMANDS: readonly string[];
+/**
+ * Remove the local-file entries from a menu; returns how many went. Idempotent, so it
+ * can run every time the menu is about to show: entries arrive from settings schemas as
+ * plugins load, not all at once.
+ */
+export declare function pruneFileMenu(menu: Menu, commands?: readonly string[]): number;
+/**
+ * Prune the menu again every time it opens. Entries arrive from settings schemas as
+ * plugins load rather than all at once, and a menu has no "about to show" signal; it
+ * is attached to the document each time it opens, which a message hook can watch.
+ */
+export declare function pruneBeforeEachOpen(menu: Menu, commands?: readonly string[]): void;
+/**
+ * Call `push` after every completed local save of every notebook, open now or later.
+ * `push` must guard against its own saves: writing the record link back to the notebook
+ * saves it again.
+ */
+export declare function routeSaves(tracker: INotebookTracker, push: (panel: NotebookPanel) => Promise<void>): void;

package/lib/share/oceanumOnly.js

@@ -0,0 +1,90 @@
+import { MessageLoop } from '@lumino/messaging';
+/** The widget id `@jupyterlab/filebrowser-extension:browser` gives the file browser. */
+export const FILE_BROWSER_ID = 'filebrowser';
+/**
+ * File menu entries that manage local files. Save, Save All and Rename stay: saving is
+ * routed to Oceanum, and renaming the local file is how a notebook gets its name.
+ */
+export const LOCAL_FILE_COMMANDS = [
+    'filebrowser:open-path',
+    'filebrowser:open-url',
+    'docmanager:save-as',
+    'docmanager:reload',
+    'docmanager:restore-checkpoint',
+    'docmanager:duplicate',
+    'docmanager:download'
+];
+/**
+ * Take the file browser out of the sidebar; true if it was there. It is closed, not
+ * disposed: other extensions hold it through IDefaultFileBrowser and still use it to
+ * open paths.
+ */
+export function hideFileBrowser(shell) {
+    for (const widget of shell.widgets('left')) {
+        if (widget.id === FILE_BROWSER_ID) {
+            widget.close();
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Submenus of local files. "Open Recent" is built by the document manager rather than
+ * declared in a schema, and its menu has no id, so it is known by the commands it holds.
+ */
+export const LOCAL_FILE_SUBMENU_COMMANDS = [
+    'docmanager:open-recent',
+    'docmanager:clear-recents'
+];
+function isLocalSubmenu(item) {
+    return (item.type === 'submenu' &&
+        !!item.submenu &&
+        (item.submenu.title.label === 'Open Recent' ||
+            item.submenu.items.some(child => LOCAL_FILE_SUBMENU_COMMANDS.includes(child.command))));
+}
+/**
+ * Remove the local-file entries from a menu; returns how many went. Idempotent, so it
+ * can run every time the menu is about to show: entries arrive from settings schemas as
+ * plugins load, not all at once.
+ */
+export function pruneFileMenu(menu, commands = LOCAL_FILE_COMMANDS) {
+    let removed = 0;
+    for (let i = menu.items.length - 1; i >= 0; i--) {
+        const item = menu.items[i];
+        if ((item.type === 'command' && commands.includes(item.command)) ||
+            isLocalSubmenu(item)) {
+            menu.removeItemAt(i);
+            removed++;
+        }
+    }
+    return removed;
+}
+/**
+ * Prune the menu again every time it opens. Entries arrive from settings schemas as
+ * plugins load rather than all at once, and a menu has no "about to show" signal; it
+ * is attached to the document each time it opens, which a message hook can watch.
+ */
+export function pruneBeforeEachOpen(menu, commands = LOCAL_FILE_COMMANDS) {
+    MessageLoop.installMessageHook(menu, (_, message) => {
+        if (message.type === 'before-attach') {
+            pruneFileMenu(menu, commands);
+        }
+        return true;
+    });
+}
+/**
+ * Call `push` after every completed local save of every notebook, open now or later.
+ * `push` must guard against its own saves: writing the record link back to the notebook
+ * saves it again.
+ */
+export function routeSaves(tracker, push) {
+    const watch = (panel) => {
+        panel.context.saveState.connect((_, state) => {
+            if (state === 'completed') {
+                void push(panel);
+            }
+        });
+    };
+    tracker.forEach(watch);
+    tracker.widgetAdded.connect((_, panel) => watch(panel));
+}

package/lib/share/plugin.d.ts

@@ -0,0 +1,21 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+export declare const CommandIDs: {
+    readonly open: "oceanum-share:open";
+    readonly save: "oceanum-share:save";
+    readonly share: "oceanum-share:share";
+    readonly rename: "oceanum-share:rename";
+    readonly delete: "oceanum-share:delete";
+};
+export declare const SHARE_PLUGIN_ID = "@oceanum/oceanumlab:share";
+/** The Notebooks tab marks each listed record with this, for its context menu. */
+export declare const SPEC_ID_ATTRIBUTE = "data-spec-id";
+export declare const NOTEBOOK_ITEM_SELECTOR = ".oceanum-notebooks-item[data-spec-id]";
+/**
+ * Open, save, share, rename and delete notebooks through the Oceanum spec store.
+ *
+ * The commands sit in the File menu, the command palette, a notebook's context menu
+ * (and its tab's), and the Notebooks tab's rows. They are enabled only while signed in.
+ * With `fileManagement: 'oceanum'` in the environment the local drive goes out of
+ * sight and every local save is pushed to the store: see `oceanumOnly.ts`.
+ */
+export declare const sharePlugin: JupyterFrontEndPlugin<void>;