jupyterlab-tour 4.0.1 → 4.1.0

package/README.md

@@ -7,7 +7,9 @@
 [![PyPI](https://img.shields.io/pypi/v/jupyterlab-tour)](https://pypi.org/project/jupyterlab-tour)
 [![conda-forge](https://img.shields.io/conda/vn/conda-forge/jupyterlab-tour)](https://anaconda.org/conda-forge/jupyterlab-tour)
 
-A JupyterLab UI Tour based on [react-joyride](https://docs.react-joyride.com).
+A JupyterLab UI Tour based on [react-joyride](https://react-joyride.com/) v2. The site
+currently only has documentation for v3. Docs for the v2 release used here are on the
+[v2.9.3 tag](https://github.com/gilbarbara/react-joyride/blob/v2.9.3/docs/SUMMARY.md).
 
 ![demo](https://raw.githubusercontent.com/jupyterlab-contrib/jupyterlab-tour/main/doc/tourDemo.gif)
 
@@ -69,7 +71,7 @@ own _Tours_ as data.
 - Open the JupyterLab _Advanced Settings_ panel <kbd>Ctrl+,</kbd>
 - Select _Tours_ from list of settings groups
 - In the editor, create JSON(5) compatible with the
-  [react-joyride data model](https://docs.react-joyride.com/props)
+  [react-joyride data model](https://github.com/gilbarbara/react-joyride/blob/v2.9.3/docs/props.md)
 - The _Tour_ will be available from the _Help Menu_, as well as the _Command Palette_
 
 ### A simple Tour
@@ -206,7 +208,7 @@ tour.stepChanged.connect((_, data) => {
 ```
 
 > `data` is an object of type
-> [`CallbackProps`](https://docs.react-joyride.com/callback).
+> [`CallbackProps`](https://github.com/gilbarbara/react-joyride/blob/v2.9.3/docs/callback.md).
 
 ## Disabling the User, Notebook, and Default Tours
 

package/lib/__tests__/plugin.spec.js

@@ -1,5 +1,6 @@
 import { Notebook, NotebookModel, NotebookPanel } from '@jupyterlab/notebook';
 import { CommandRegistry } from '@lumino/commands';
+import { PromiseDelegate } from '@lumino/coreutils';
 import { DocumentRegistry } from '@jupyterlab/docregistry';
 import { ServerConnection } from '@jupyterlab/services';
 import { CodeMirrorEditorFactory, CodeMirrorMimeTypeService, EditorLanguageRegistry } from '@jupyterlab/codemirror';
@@ -8,14 +9,30 @@ import 'jest';
 import { CommandIDs } from '../constants';
 import plugin from '../index';
 import { NS } from '../tokens';
+import * as nbformat from '@jupyterlab/nbformat';
+import { YNotebook } from '@jupyter/ydoc';
 const DEFAULT_TOURS_SIZE = 2;
 const [corePlugin, userPlugin, notebookPlugin, defaultsPlugin] = plugin;
+async function mockFetch(input, init) {
+    if (!(typeof input == 'object' &&
+        input.url.match(/api\/config\/jupyterlabtourplugin/) != null)) {
+        throw new Error(`cannot handle ${input}`);
+    }
+    return {
+        status: 200,
+        json: async () => {
+            return {};
+        }
+    };
+}
 function mockApp() {
     return {
         commands: new CommandRegistry(),
         restored: Promise.resolve(),
         docRegistry: new DocumentRegistry(),
-        serviceManager: { serverSettings: ServerConnection.makeSettings() }
+        serviceManager: {
+            serverSettings: ServerConnection.makeSettings({ fetch: mockFetch })
+        }
     };
 }
 function aTour() {
@@ -128,15 +145,28 @@ describe(notebookPlugin.id, () => {
                 mimeTypeService,
                 contentFactory: new NotebookPanel.ContentFactory({ editorFactory })
             });
-            const model = new NotebookModel();
+            const sharedModel = YNotebook.create({
+                data: {
+                    nbformat: nbformat.MAJOR_VERSION,
+                    nbformat_minor: nbformat.MINOR_VERSION,
+                    metadata: {
+                        kernelspec: { name: '', display_name: '' },
+                        language_info: { name: '' }
+                    }
+                }
+            });
+            const model = new NotebookModel({ sharedModel });
             notebook.model = model;
             notebookTourManager.addNotebook(notebook);
             expect(notebookTourManager.tourManager.tours.size).toBe(0);
-            model.setMetadata(NS, {
-                tours: [aTour()]
-            });
+            let changed = new PromiseDelegate();
+            notebookTourManager.notebookToursChanged.connect(() => changed.resolve());
+            model.setMetadata(NS, { tours: [aTour()] });
+            await changed.promise;
+            changed = new PromiseDelegate();
             expect(notebookTourManager.tourManager.tours.size).toBe(1);
             model.deleteMetadata(NS);
+            await changed.promise;
             expect(notebookTourManager.tourManager.tours.size).toBe(0);
         });
     });

package/lib/__tests__/tour.spec.d.ts

@@ -0,0 +1 @@
+import 'jest';

package/lib/__tests__/tour.spec.js

@@ -0,0 +1,86 @@
+import 'jest';
+import { STATUS } from 'react-joyride';
+import { TourManager } from '../tourManager';
+import { TourHandler } from '../tour';
+function event(status, index) {
+    return { status, index, step: { target: 'body', content: '' } };
+}
+function runningTour(controlled = false) {
+    const tour = new TourHandler('tour', 'Tour', undefined, null, 0, controlled);
+    tour.addStep({ target: 'body', content: 'one' });
+    tour.addStep({ target: 'body', content: 'two' });
+    tour.handleTourEvent(event(STATUS.RUNNING, 0));
+    return tour;
+}
+describe('TourHandler', () => {
+    it('leaves the tour uncontrolled by default', () => {
+        const tour = new TourHandler('tour', 'Tour');
+        expect(tour.controlled).toBe(false);
+        expect(tour.currentStepIndex).toBe(-1);
+        expect(tour.isRunning()).toBe(false);
+    });
+    it('updates the shared index when a controlled tour sets currentStepIndex', () => {
+        const tour = new TourHandler('tour', 'Tour', undefined, null, 0, true);
+        tour.currentStepIndex = 2;
+        expect(tour.currentStepIndex).toBe(2);
+        expect(tour.isRunning()).toBe(true);
+    });
+    it('follows Joyride callbacks on an uncontrolled tour', () => {
+        const tour = runningTour(false);
+        expect(tour.currentStepIndex).toBe(0);
+        tour.handleTourEvent(event(STATUS.RUNNING, 1));
+        expect(tour.currentStepIndex).toBe(1);
+    });
+    it('stores a currentStepIndex write on an uncontrolled tour', () => {
+        const tour = runningTour(false);
+        tour.currentStepIndex = 1;
+        expect(tour.currentStepIndex).toBe(1);
+    });
+    it('keeps a controlled currentStepIndex when Joyride reports another index', () => {
+        const tour = runningTour(true);
+        tour.currentStepIndex = 1;
+        tour.handleTourEvent(event(STATUS.RUNNING, 0));
+        expect(tour.currentStepIndex).toBe(1);
+    });
+    it('returns to idle when the tour finishes', () => {
+        const tour = runningTour(false);
+        tour.handleTourEvent(event(STATUS.FINISHED, 1));
+        expect(tour.currentStepIndex).toBe(-1);
+        expect(tour.isRunning()).toBe(false);
+    });
+});
+describe('TourManager', () => {
+    it('resets currentStepIndex when a controlled tour is launched', async () => {
+        const manager = new TourManager();
+        const handler = manager.addTour({
+            id: 'sample',
+            label: 'Sample',
+            hasHelpEntry: false,
+            controlled: true,
+            steps: [{ target: 'body', content: 'one', placement: 'center' }]
+        });
+        if (!handler) {
+            throw new Error('tour was not created');
+        }
+        handler.currentStepIndex = 1;
+        await manager.launch([handler], true);
+        expect(handler.currentStepIndex).toBe(0);
+        manager.dispose();
+    });
+    it('does not reset currentStepIndex when an uncontrolled tour is launched', async () => {
+        const manager = new TourManager();
+        const handler = manager.addTour({
+            id: 'sample',
+            label: 'Sample',
+            hasHelpEntry: false,
+            steps: [{ target: 'body', content: 'one', placement: 'center' }]
+        });
+        if (!handler) {
+            throw new Error('tour was not created');
+        }
+        handler.handleTourEvent(event(STATUS.RUNNING, 1));
+        await manager.launch([handler], true);
+        expect(handler.currentStepIndex).toBe(1);
+        manager.dispose();
+    });
+});

package/lib/components.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="react" />
-import { ISignal } from '@lumino/signaling';
-import { ITourManager } from './tokens';
-import { TourHandler } from './tour';
+import type { ISignal } from '@lumino/signaling';
+import type { ITourManager } from './tokens';
+import type { TourHandler } from './tour';
 /**
  * Tour container
  */

package/lib/components.js

@@ -18,8 +18,9 @@ class Tour extends React.Component {
         };
         this._handleJoyrideCallback = (data) => {
             const { status } = data;
+            const handler = this.props.tours[this.state.index];
             const finishedStatuses = [STATUS.FINISHED, STATUS.SKIPPED];
-            this.props.tours[this.state.index].handleTourEvent(data);
+            handler.handleTourEvent(data);
             if (finishedStatuses.includes(status)) {
                 this.setState({ run: false });
                 const newIndex = this.state.index + 1;
@@ -37,7 +38,18 @@ class Tour extends React.Component {
         };
     }
     render() {
-        return this.props.tours && this.props.tours[this.state.index] ? (React.createElement(ReactJoyride, { key: this.props.tours[this.state.index].id, ...this.props.tours[this.state.index].options, callback: this._handleJoyrideCallback, run: this.state.run, steps: this.props.tours[this.state.index].steps })) : null;
+        var _a;
+        const handler = (_a = this.props.tours) === null || _a === void 0 ? void 0 : _a[this.state.index];
+        if (!handler) {
+            return null;
+        }
+        const options = { ...handler.options };
+        delete options.stepIndex;
+        const joyride = (stepIndex) => (React.createElement(ReactJoyride, { key: handler.id, ...options, callback: this._handleJoyrideCallback, run: this.state.run, steps: handler.steps, ...(stepIndex === undefined ? {} : { stepIndex }) }));
+        if (!handler.controlled) {
+            return joyride();
+        }
+        return (React.createElement(UseSignal, { signal: handler.currentStepIndexChanged, initialArgs: handler.currentStepIndex }, () => joyride(handler.currentStepIndex >= 0 ? handler.currentStepIndex : undefined)));
     }
 }
 /**

package/lib/constants.d.ts

@@ -1,4 +1,4 @@
-import { Props as JoyrideProps } from 'react-joyride';
+import type { Props as JoyrideProps } from 'react-joyride';
 /**
  * Command IDs
  */

package/lib/defaults.d.ts

@@ -1,6 +1,6 @@
-import { JupyterFrontEnd } from '@jupyterlab/application';
-import { INotebookTracker } from '@jupyterlab/notebook';
-import { ITourManager } from './tokens';
+import type { JupyterFrontEnd } from '@jupyterlab/application';
+import type { INotebookTracker } from '@jupyterlab/notebook';
+import type { ITourManager } from './tokens';
 /**
  * Add all default tours
  *

package/lib/notebookButton.d.ts

@@ -1,8 +1,8 @@
 import * as React from 'react';
 import { ReactWidget } from '@jupyterlab/apputils';
-import { Notebook } from '@jupyterlab/notebook';
-import { TranslationBundle } from '@jupyterlab/translation';
-import { INotebookTourManager } from './tokens';
+import type { Notebook } from '@jupyterlab/notebook';
+import type { TranslationBundle } from '@jupyterlab/translation';
+import type { INotebookTourManager } from './tokens';
 export declare class TourButton extends ReactWidget {
     /**
      * Construct a new notebook toolbar item for tours

package/lib/notebookTourManager.d.ts

@@ -1,7 +1,7 @@
-import { ErrorObject } from 'ajv';
-import { Notebook } from '@jupyterlab/notebook';
-import { ISignal } from '@lumino/signaling';
-import { INotebookTourManager, ITourManager } from './tokens';
+import type { ErrorObject, ValidateFunction } from 'ajv';
+import type { Notebook } from '@jupyterlab/notebook';
+import type { ISignal } from '@lumino/signaling';
+import type { INotebookTourManager, ITourManager } from './tokens';
 /**
  * The NotebookTourManager is needed to sync Notebook metadata with the TourManager
  */
@@ -24,13 +24,19 @@ export declare class NotebookTourManager implements INotebookTourManager {
      * @returns the list of errors
      */
     getNotebookValidationErrors(notebook: Notebook): ErrorObject[];
+    /** A signal that emits when notebook tours changes. */
     get notebookToursChanged(): ISignal<INotebookTourManager, Notebook>;
     private _onNotebookDisposed;
     private _cleanNotebookTours;
     /**
-     * The metadata changed, and therefor maybe tours: remove and re-add all of them.
+     * The metadata changed, and therefore maybe tours: remove all of them, and
+     * maybe re-add.
      */
     private _notebookMetadataChanged;
+    /**
+     * Tour metadata was found:
+     */
+    private _updateFromNotebookMetadata;
     /**
      * Actually create a tour from JSON
      */
@@ -38,6 +44,12 @@ export declare class NotebookTourManager implements INotebookTourManager {
     private _tourManager;
     private _notebookTours;
     private _notebookToursChanged;
-    private _validator;
     private _validationErrors;
 }
+/** A namespace for private values. */
+export declare namespace Private {
+    /**
+     * Get a singleton pre-compiled validator function.
+     */
+    function ensureValidator(): Promise<ValidateFunction>;
+}

package/lib/notebookTourManager.js

@@ -1,8 +1,7 @@
-import Ajv from 'ajv';
 import { Signal } from '@lumino/signaling';
-import USER_SCHEMA from '../schema/user-tours.json';
 import { notebookTourIcon } from './icons';
 import { NOTEBOOK_PLUGIN_ID, NS } from './tokens';
+import { PromiseDelegate } from '@lumino/coreutils';
 /**
  * The NotebookTourManager is needed to sync Notebook metadata with the TourManager
  */
@@ -12,10 +11,6 @@ export class NotebookTourManager {
         this._notebookToursChanged = new Signal(this);
         this._validationErrors = new Map();
         this._tourManager = options.tourManager;
-        // `jupyter.lab...` keywords custom keywords rejected by default
-        // we may be able to do better than `strict: false` by defining
-        // custom keywords https://ajv.js.org/keywords.html
-        this._validator = new Ajv({ strict: false }).compile(USER_SCHEMA);
     }
     get tourManager() {
         return this._tourManager;
@@ -31,11 +26,9 @@ export class NotebookTourManager {
         if (!notebook.model) {
             return;
         }
-        ((_a = notebook.model.metadataChanged) !== null && _a !== void 0 ? _a : notebook.model.metadata.changed).connect(() => {
-            this._notebookMetadataChanged(notebook);
-        });
+        ((_a = notebook.model.metadataChanged) !== null && _a !== void 0 ? _a : notebook.model.metadata.changed).connect(async () => await this._notebookMetadataChanged(notebook));
         notebook.disposed.connect(this._onNotebookDisposed, this);
-        this._notebookMetadataChanged(notebook);
+        await this._notebookMetadataChanged(notebook);
     }
     /**
      * Get the list of full tour ids for this notebook
@@ -59,6 +52,7 @@ export class NotebookTourManager {
     getNotebookValidationErrors(notebook) {
         return this._validationErrors.get(notebook) || [];
     }
+    /** A signal that emits when notebook tours changes. */
     get notebookToursChanged() {
         return this._notebookToursChanged;
     }
@@ -71,10 +65,10 @@ export class NotebookTourManager {
         }
     }
     /**
-     * The metadata changed, and therefor maybe tours: remove and re-add all of them.
+     * The metadata changed, and therefore maybe tours: remove all of them, and
+     * maybe re-add.
      */
-    _notebookMetadataChanged(notebook) {
-        var _a, _b;
+    async _notebookMetadataChanged(notebook) {
         const { model } = notebook;
         const metadata = model
             ? model.getMetadata
@@ -82,34 +76,42 @@ export class NotebookTourManager {
                 : // @ts-expect-error JLab 3 API
                     model.metadata.get(NS)
             : null;
-        const trans = this._tourManager.translator;
         this._cleanNotebookTours(notebook);
         this._validationErrors.set(notebook, []);
         if (metadata) {
-            this._validator(metadata);
-            const errors = this._validator.errors || [];
-            this._validationErrors.set(notebook, errors);
-            if (errors.length) {
-                console.error(trans.__('Validation errors found: fix them in Advanced Settings'));
-                console.table(errors);
-            }
-            else {
-                const tours = (_a = metadata['tours']) !== null && _a !== void 0 ? _a : [];
-                for (const tour of this.tourManager.sortTours(tours)) {
-                    try {
-                        this._addNotebookTour(notebook, tour);
-                        this._tourManager.launch([tour.id], false);
-                    }
-                    catch (error) {
-                        console.groupCollapsed(trans.__('Error encountered adding notebook tour %1 (%2)', tour.label, tour.id), error);
-                        console.table(tour.steps);
-                        console.log((_b = tour.options) !== null && _b !== void 0 ? _b : {});
-                        console.groupEnd();
-                    }
+            await this._updateFromNotebookMetadata(notebook, metadata);
+        }
+        this._notebookToursChanged.emit(notebook);
+    }
+    /**
+     * Tour metadata was found:
+     */
+    async _updateFromNotebookMetadata(notebook, metadata) {
+        var _a, _b;
+        const { translator } = this._tourManager;
+        const _validator = await Private.ensureValidator();
+        _validator(metadata);
+        const errors = _validator.errors || [];
+        this._validationErrors.set(notebook, errors);
+        if (errors.length) {
+            console.error(translator.__('Validation errors found: fix them in Advanced Settings'));
+            console.table(errors);
+        }
+        else {
+            const tours = (_a = metadata['tours']) !== null && _a !== void 0 ? _a : [];
+            for (const tour of this.tourManager.sortTours(tours)) {
+                try {
+                    this._addNotebookTour(notebook, tour);
+                    this._tourManager.launch([tour.id], false);
+                }
+                catch (error) {
+                    console.groupCollapsed(translator.__('Error encountered adding notebook tour %1 (%2)', tour.label, tour.id), error);
+                    console.table(tour.steps);
+                    console.log((_b = tour.options) !== null && _b !== void 0 ? _b : {});
+                    console.groupEnd();
                 }
             }
         }
-        this._notebookToursChanged.emit(notebook);
     }
     /**
      * Actually create a tour from JSON
@@ -122,3 +124,27 @@ export class NotebookTourManager {
         });
     }
 }
+/** A namespace for private values. */
+export var Private;
+(function (Private) {
+    let _validator = null;
+    let _loading = null;
+    /**
+     * Get a singleton pre-compiled validator function.
+     */
+    async function ensureValidator() {
+        if (!_loading) {
+            _loading = new PromiseDelegate();
+            const { Ajv } = await import('ajv');
+            const schema = await import('../schema/user-tours.json');
+            // `jupyter.lab...` keywords custom keywords rejected by default
+            // we may be able to do better than `strict: false` by defining
+            // custom keywords https://ajv.js.org/keywords.html
+            const ajv = new Ajv({ strict: false });
+            _validator = ajv.compile(schema);
+            _loading.resolve(_validator);
+        }
+        return _loading.promise;
+    }
+    Private.ensureValidator = ensureValidator;
+})(Private || (Private = {}));

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "jupyterlab-tour",
-    "version": "4.0.1",
+    "version": "4.1.0",
     "description": "A JupyterLab UI Tour.",
     "keywords": [
         "jupyter",
@@ -31,8 +31,8 @@
     },
     "scripts": {
         "build": "jlpm build:lib && jlpm build:labextension:dev",
-        "build:labextension": "jupyter labextension build --debug .",
-        "build:labextension:dev": "jupyter labextension build --debug --development True .",
+        "build:labextension": "jupyter-builder build --debug .",
+        "build:labextension:dev": "jupyter-builder build --debug --development True .",
         "build:lib": "jlpm build:lib:prod --sourceMap",
         "build:lib:prod": "tsc -b src",
         "build:prod": "jlpm clean && jlpm build:lib:prod && jlpm build:labextension",
@@ -41,7 +41,7 @@
         "clean:labextension": "rimraf jupyterlab_tour/labextension jupyterlab_tour/_version.py",
         "clean:lib": "rimraf lib build/.cache/tsc",
         "clean:lintcache": "rimraf ./build/.cache/eslint ./build/.cache/stylelint",
-        "dedupe": "yarn-berry-deduplicate --strategy=fewer --fail",
+        "dedupe": "yarn dedupe --check",
         "eslint": "jlpm eslint:check --fix",
         "eslint:check": "eslint . --cache --cache-location=./build/.cache/eslint --ext .ts,.tsx",
         "install:extension": "jlpm build",
@@ -54,32 +54,32 @@
         "stylelint:check": "stylelint --cache --cache-location=./build/.cache/stylelint \"style/**/*.css\"",
         "test": "jest --coverage",
         "watch": "run-p watch:src watch:labextension",
-        "watch:labextension": "jupyter labextension watch .",
+        "watch:labextension": "jupyter-builder watch .",
         "watch:src": "jlpm build:lib -w"
     },
     "dependencies": {
-        "@jupyterlab/application": "^4.0.0",
-        "@jupyterlab/apputils": "^4.0.0",
-        "@jupyterlab/mainmenu": "^4.0.0",
-        "@jupyterlab/notebook": "^4.0.0",
-        "@jupyterlab/services": "^7.0.0",
-        "@jupyterlab/settingregistry": "^4.0.0",
-        "@jupyterlab/statedb": "^4.0.0",
-        "@jupyterlab/translation": "^4.0.0",
-        "@jupyterlab/ui-components": "^4.0.0",
+        "@jupyterlab/application": "^4.3.0",
+        "@jupyterlab/apputils": "^4.3.0",
+        "@jupyterlab/mainmenu": "^4.3.0",
+        "@jupyterlab/notebook": "^4.3.0",
+        "@jupyterlab/services": "^7.3.0",
+        "@jupyterlab/settingregistry": "^4.3.0",
+        "@jupyterlab/statedb": "^4.3.0",
+        "@jupyterlab/translation": "^4.3.0",
+        "@jupyterlab/ui-components": "^4.3.0",
         "@lumino/coreutils": "^2.1.1",
         "@lumino/disposable": "^2.1.1",
         "@lumino/signaling": "^2.1.1",
-        "@lumino/widgets": "^2.1.1",
-        "ajv": "^8.12.0",
+        "@lumino/widgets": "^2.3.1",
+        "ajv": "^8.17.1",
         "react": "^18.2.0",
-        "react-joyride": "^2.5.5"
+        "react-joyride": "^2.9.3"
     },
     "devDependencies": {
         "@babel/core": "^7.20.12",
         "@babel/preset-env": "^7.20.2",
-        "@jupyterlab/builder": "^4.0.0",
-        "@jupyterlab/testutils": "^4.0.0",
+        "@jupyter/builder": "^1.2.1",
+        "@jupyterlab/testutils": "^4.3.0",
         "@types/jest": "^29.2.0",
         "@types/json-schema": "^7.0.11",
         "@types/react": "^18.0.26",
@@ -93,8 +93,8 @@
         "eslint-plugin-react-hooks": "^4.6.0",
         "jest": "^29.2.0",
         "npm-run-all": "^4.1.5",
-        "prettier": "^3.0.0",
-        "rimraf": "^5.0.1",
+        "prettier": "^3.6.2",
+        "rimraf": "^6.1.2",
         "source-map-loader": "^1.0.2",
         "style-loader": "^3.3.1",
         "stylelint": "^15.10.1",
@@ -102,7 +102,6 @@
         "stylelint-config-standard": "^34.0.0",
         "ts-jest": "^29.1.1",
         "typescript": "~5.0.4",
-        "yarn-berry-deduplicate": "^6.1.1",
         "yjs": "^13.5.40"
     },
     "sideEffects": [
@@ -110,14 +109,25 @@
         "style/index.js"
     ],
     "resolutions": {
-        "@types/node": "^18.0.0",
+        "@types/node": "^22.10.1",
         "@types/react": "^18.0.26",
-        "react": "^18.2.0"
+        "react": "^18.2.0",
+        "yjs": "^13.5.40"
     },
     "jupyterlab": {
         "extension": true,
         "schemaDir": "schema",
-        "outputDir": "jupyterlab_tour/labextension"
+        "outputDir": "jupyterlab_tour/labextension",
+        "sharedPackages": {
+            "ajv": {
+                "bundled": true,
+                "singleton": false
+            },
+            "react-joyride": {
+                "bundled": true,
+                "singleton": false
+            }
+        }
     },
     "styleModule": "style/index.js",
     "eslintIgnore": [
@@ -165,6 +175,13 @@
                     "args": "none"
                 }
             ],
+            "@typescript-eslint/consistent-type-imports": [
+                "error",
+                {
+                    "prefer": "type-imports",
+                    "fixStyle": "separate-type-imports"
+                }
+            ],
             "@typescript-eslint/no-explicit-any": "off",
             "@typescript-eslint/no-namespace": "off",
             "@typescript-eslint/no-use-before-define": "off",
@@ -197,6 +214,13 @@
                 "options": {
                     "tabWidth": 4
                 }
+            },
+            {
+                "files": ".github/workflows/*.yml",
+                "options": {
+                    "proseWrap": "never",
+                    "printWidth": 120
+                }
             }
         ]
     },

package/lib/plugin.d.ts

@@ -1,4 +1,4 @@
-import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+import type { JupyterFrontEndPlugin } from '@jupyterlab/application';
 import { INotebookTourManager, ITourManager, IUserTourManager } from './tokens';
-declare const _default: (JupyterFrontEndPlugin<void> | JupyterFrontEndPlugin<ITourManager> | JupyterFrontEndPlugin<IUserTourManager> | JupyterFrontEndPlugin<INotebookTourManager>)[];
+declare const _default: (JupyterFrontEndPlugin<ITourManager> | JupyterFrontEndPlugin<IUserTourManager> | JupyterFrontEndPlugin<INotebookTourManager> | JupyterFrontEndPlugin<void>)[];
 export default _default;

package/lib/plugin.js

@@ -163,10 +163,13 @@ function activateDefaults(app, tourManager, nbTracker) {
     if (nbTracker &&
         (app.name !== 'Jupyter Notebook' ||
             window.location.pathname.match(/\/notebooks\/.+$/))) {
+        let hasOfferedNotebookTour = false;
         nbTracker.widgetAdded.connect(() => {
-            if (tourManager.tours.has(NOTEBOOK_ID)) {
-                tourManager.launch([NOTEBOOK_ID], false);
+            if (hasOfferedNotebookTour || !tourManager.tours.has(NOTEBOOK_ID)) {
+                return;
             }
+            hasOfferedNotebookTour = true;
+            void tourManager.launch([NOTEBOOK_ID], false);
         });
     }
     Promise.all([app.restored, tourManager.ready]).then(() => {

package/lib/schema/user-tours.json

@@ -11,7 +11,7 @@
     "properties": {
         "tours": {
             "type": "array",
-            "description": "An array of a tours. Each requires an `id`, `label` and `steps[]`, and may have `options`, see https://docs.react-joyride.com",
+            "description": "An array of tours. Each requires an `id`, `label` and `steps[]`, and may have `options`. For `steps` and `options`, see https://github.com/gilbarbara/react-joyride/blob/v2.9.3/docs/SUMMARY.md",
             "default": [],
             "items": {
                 "type": "object",

package/lib/tokens.d.ts

@@ -1,13 +1,13 @@
-import { ErrorObject } from 'ajv';
-import { ISettingRegistry } from '@jupyterlab/settingregistry';
-import { ITranslator, TranslationBundle } from '@jupyterlab/translation';
-import { Notebook } from '@jupyterlab/notebook';
+import type { ErrorObject } from 'ajv';
+import type { ISettingRegistry } from '@jupyterlab/settingregistry';
+import type { ITranslator, TranslationBundle } from '@jupyterlab/translation';
+import type { Notebook } from '@jupyterlab/notebook';
 import { Token } from '@lumino/coreutils';
-import { IDisposable } from '@lumino/disposable';
-import { ISignal } from '@lumino/signaling';
-import { LabIcon, RankedMenu } from '@jupyterlab/ui-components';
-import React from 'react';
-import { CallBackProps, Placement, Props as JoyrideProps, Step } from 'react-joyride';
+import type { IDisposable } from '@lumino/disposable';
+import type { ISignal } from '@lumino/signaling';
+import type { LabIcon, RankedMenu } from '@jupyterlab/ui-components';
+import type React from 'react';
+import type { CallBackProps, Placement, Props as JoyrideProps, Step } from 'react-joyride';
 /**
  * Namespace for everything
  */
@@ -93,7 +93,7 @@ export interface ITour {
     /**
      * Tour options
      *
-     * @see https://docs.react-joyride.com/props
+     * @see https://github.com/gilbarbara/react-joyride/blob/v2.9.3/docs/props.md
      *
      * #### Notes
      *
@@ -113,6 +113,11 @@ export interface ITour {
      * Translation domain for this tour
      */
     translation?: string;
+    /**
+     * When true, the tour step is driven by {@link ITourHandler.currentStepIndex}.
+     * Default is false, which leaves Joyride uncontrolled.
+     */
+    controlled?: boolean;
 }
 /**
  * Tour handler interface
@@ -137,8 +142,9 @@ export interface ITourHandler extends IDisposable {
     createAndAddStep(target: string, content: React.ReactNode, placement?: StepPlacement, title?: string): Step;
     /**
      * The index of the current step of the tour. Returns -1 if tour isn't active.
+     * Setting this moves the tour only when {@link controlled} is true.
      */
-    readonly currentStepIndex: number;
+    currentStepIndex: number;
     /**
      * Is the tour running?
      */
@@ -191,6 +197,15 @@ export interface ITourHandler extends IDisposable {
      * A signal emitted when the tour step has changed.
      */
     readonly stepChanged: ISignal<this, CallBackProps>;
+    /**
+     * When true, Joyride is controlled by {@link currentStepIndex}.
+     * When false, Joyride advances on its own.
+     */
+    readonly controlled: boolean;
+    /**
+     * A signal emitted when {@link currentStepIndex} changes.
+     */
+    readonly currentStepIndexChanged: ISignal<this, number>;
     /**
      * The array of steps the tour currently contains. Each step will be followed
      * in order as the tour progresses.

package/lib/tour.d.ts

@@ -1,14 +1,16 @@
 /// <reference types="react" />
-import { ISignal } from '@lumino/signaling';
-import { LabIcon } from '@jupyterlab/ui-components';
-import { CallBackProps, Props as JoyrideProps, Step } from 'react-joyride';
-import { ITourHandler, StepPlacement } from './tokens';
+import type { ISignal } from '@lumino/signaling';
+import type { LabIcon } from '@jupyterlab/ui-components';
+import type { CallBackProps, Props as JoyrideProps, Step } from 'react-joyride';
+import type { ITourHandler, StepPlacement } from './tokens';
 export declare class TourHandler implements ITourHandler {
-    constructor(id: string, label: string, options?: Omit<JoyrideProps, 'steps'>, icon?: LabIcon | null, version?: number);
+    constructor(id: string, label: string, options?: Omit<JoyrideProps, 'steps'>, icon?: LabIcon | null, version?: number, controlled?: boolean);
     /**
      * The index of the current step of the tour. Returns -1 if tour isn't active.
+     * Setting this moves the tour only when {@link controlled} is true.
      */
     get currentStepIndex(): number;
+    set currentStepIndex(index: number);
     /**
      * A signal emitted when all the steps of the tour have been seen and tour is finished.
      */
@@ -51,6 +53,14 @@ export declare class TourHandler implements ITourHandler {
      * A signal emitted when the tour step has changed.
      */
     get stepChanged(): ISignal<this, CallBackProps>;
+    /**
+     * When true, Joyride is controlled by {@link currentStepIndex}.
+     */
+    get controlled(): boolean;
+    /**
+     * A signal emitted when {@link currentStepIndex} changes.
+     */
+    get currentStepIndexChanged(): ISignal<this, number>;
     /**
      * The array of steps the tour currently contains. Each step will be followed
      * in order as the tour progresses.
@@ -114,14 +124,15 @@ export declare class TourHandler implements ITourHandler {
     private _finished;
     private _started;
     private _stepChanged;
+    private _currentStepIndexChanged;
     private _currentStepIndex;
     private _id;
     private _isDisposed;
     private _label;
     private _options;
     private _previousStatus;
-    private _previousStepIndex;
     private _steps;
     private _icon;
     private _version;
+    private _controlled;
 }

package/lib/tour.js

@@ -5,7 +5,7 @@ import { TutorialDefaultOptions } from './constants';
 import { tourIcon } from './icons';
 // TODO should be IDisposable !! handling signal connection clearance
 export class TourHandler {
-    constructor(id, label, options, icon = null, version = -1) {
+    constructor(id, label, options, icon = null, version = -1, controlled = false) {
         /**
          * Handle react-joyride callbacks
          *
@@ -19,7 +19,7 @@ export class TourHandler {
             // Handle status changes when they occur
             if (status !== this._previousStatus) {
                 this._previousStatus = status;
-                this._currentStepIndex = -1;
+                this.currentStepIndex = -1;
                 if (status === STATUS.FINISHED) {
                     this._finished.emit(data);
                 }
@@ -27,7 +27,7 @@ export class TourHandler {
                     this._skipped.emit(data);
                 }
                 else if (status === STATUS.RUNNING) {
-                    this._currentStepIndex = 0;
+                    this.currentStepIndex = 0;
                     this._started.emit(data);
                 }
                 else if (status === STATUS.ERROR) {
@@ -36,9 +36,8 @@ export class TourHandler {
             }
             // Emit step change event
             if (status === STATUS.RUNNING) {
-                if (index !== this._previousStepIndex) {
-                    this._previousStepIndex = index;
-                    this._currentStepIndex = data.index;
+                if (!this._controlled) {
+                    this.currentStepIndex = index;
                 }
                 this._stepChanged.emit(data);
             }
@@ -47,15 +46,17 @@ export class TourHandler {
         this._finished = new Signal(this);
         this._started = new Signal(this);
         this._stepChanged = new Signal(this);
+        this._currentStepIndexChanged = new Signal(this);
         this._currentStepIndex = -1;
         this._isDisposed = false;
         this._previousStatus = STATUS.READY;
-        this._previousStepIndex = -1;
         this._steps = new Array();
+        this._controlled = false;
         this._label = label;
         this._id = id;
         this._icon = icon || null;
         this._version = version;
+        this._controlled = controlled;
         const { styles, ...others } = options !== null && options !== void 0 ? options : {};
         this._options = { ...TutorialDefaultOptions, ...others };
         if (!this._options.styles) {
@@ -68,10 +69,18 @@ export class TourHandler {
     }
     /**
      * The index of the current step of the tour. Returns -1 if tour isn't active.
+     * Setting this moves the tour only when {@link controlled} is true.
      */
     get currentStepIndex() {
         return this._currentStepIndex;
     }
+    set currentStepIndex(index) {
+        if (index === this._currentStepIndex) {
+            return;
+        }
+        this._currentStepIndex = index;
+        this._currentStepIndexChanged.emit(index);
+    }
     /**
      * A signal emitted when all the steps of the tour have been seen and tour is finished.
      */
@@ -136,6 +145,18 @@ export class TourHandler {
     get stepChanged() {
         return this._stepChanged;
     }
+    /**
+     * When true, Joyride is controlled by {@link currentStepIndex}.
+     */
+    get controlled() {
+        return this._controlled;
+    }
+    /**
+     * A signal emitted when {@link currentStepIndex} changes.
+     */
+    get currentStepIndexChanged() {
+        return this._currentStepIndexChanged;
+    }
     /**
      * The array of steps the tour currently contains. Each step will be followed
      * in order as the tour progresses.

package/lib/tourManager.d.ts

@@ -1,7 +1,7 @@
-import { ISignal } from '@lumino/signaling';
-import { TranslationBundle } from '@jupyterlab/translation';
+import type { ISignal } from '@lumino/signaling';
+import type { TranslationBundle } from '@jupyterlab/translation';
 import { LabIcon } from '@jupyterlab/ui-components';
-import { ITour, ITourHandler, ITourManager, ITourManagerOptions } from './tokens';
+import type { ITour, ITourHandler, ITourManager, ITourManagerOptions } from './tokens';
 import { TourHandler } from './tour';
 /**
  * The TourManager is needed to manage creation, removal and launching of Tutorials

package/lib/tourManager.js

@@ -24,12 +24,13 @@ export class TourManager {
          * The tour label will not be translated.
          */
         this.createTour = (args) => {
-            var _a, _b, _c, _d;
+            var _a, _b, _c, _d, _e;
             const { id, label } = args;
             const addToHelpMenu = (_a = args.hasHelpEntry) !== null && _a !== void 0 ? _a : true;
             const options = (_b = args.options) !== null && _b !== void 0 ? _b : {};
             const icon = (_c = args.icon) !== null && _c !== void 0 ? _c : null;
             const version = (_d = args.version) !== null && _d !== void 0 ? _d : 0;
+            const controlled = (_e = args.controlled) !== null && _e !== void 0 ? _e : false;
             if (this._tours.has(id)) {
                 throw new Error(this._trans.__("Error creating new tour. TourHandler id's must be unique.\nTutorial with the id: '%1' already exists.", id));
             }
@@ -38,7 +39,7 @@ export class TourManager {
                 options.locale = this._locale;
             }
             // Create tour and add it to help menu if needed
-            const newTutorial = new TourHandler(id, label, options, icon, version);
+            const newTutorial = new TourHandler(id, label, options, icon, version, controlled);
             if (this._menu && addToHelpMenu) {
                 const options = {
                     args: {
@@ -173,7 +174,8 @@ export class TourManager {
                 hasHelpEntry: tour.hasHelpEntry === false ? false : true,
                 options: tour.options,
                 icon: tour.icon ? LabIcon.resolve({ icon: tour.icon }) : undefined,
-                version: tour.version
+                version: tour.version,
+                controlled: tour.controlled
             });
             tour.steps.forEach(step => {
                 const translatedStep = { ...step };
@@ -229,6 +231,11 @@ export class TourManager {
                 : !this._state.map(s => s.id).includes(tour.id));
         }
         const startTours = () => {
+            tourList.forEach(tour => {
+                if (tour.controlled) {
+                    tour.currentStepIndex = 0;
+                }
+            });
             this._activeTours = tourList;
             this._tourLaunched.emit(tourList);
         };

package/lib/userTourManager.d.ts

@@ -1,4 +1,4 @@
-import { ITourManager, IUserTourManager } from './tokens';
+import type { ITourManager, IUserTourManager } from './tokens';
 /**
  * The UserTourManager is needed to manage syncing of user settings with the TourManager
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "jupyterlab-tour",
-    "version": "4.0.1",
+    "version": "4.1.0",
     "description": "A JupyterLab UI Tour.",
     "keywords": [
         "jupyter",
@@ -31,8 +31,8 @@
     },
     "scripts": {
         "build": "jlpm build:lib && jlpm build:labextension:dev",
-        "build:labextension": "jupyter labextension build --debug .",
-        "build:labextension:dev": "jupyter labextension build --debug --development True .",
+        "build:labextension": "jupyter-builder build --debug .",
+        "build:labextension:dev": "jupyter-builder build --debug --development True .",
         "build:lib": "jlpm build:lib:prod --sourceMap",
         "build:lib:prod": "tsc -b src",
         "build:prod": "jlpm clean && jlpm build:lib:prod && jlpm build:labextension",
@@ -41,7 +41,7 @@
         "clean:labextension": "rimraf jupyterlab_tour/labextension jupyterlab_tour/_version.py",
         "clean:lib": "rimraf lib build/.cache/tsc",
         "clean:lintcache": "rimraf ./build/.cache/eslint ./build/.cache/stylelint",
-        "dedupe": "yarn-berry-deduplicate --strategy=fewer --fail",
+        "dedupe": "yarn dedupe --check",
         "eslint": "jlpm eslint:check --fix",
         "eslint:check": "eslint . --cache --cache-location=./build/.cache/eslint --ext .ts,.tsx",
         "install:extension": "jlpm build",
@@ -54,32 +54,32 @@
         "stylelint:check": "stylelint --cache --cache-location=./build/.cache/stylelint \"style/**/*.css\"",
         "test": "jest --coverage",
         "watch": "run-p watch:src watch:labextension",
-        "watch:labextension": "jupyter labextension watch .",
+        "watch:labextension": "jupyter-builder watch .",
         "watch:src": "jlpm build:lib -w"
     },
     "dependencies": {
-        "@jupyterlab/application": "^4.0.0",
-        "@jupyterlab/apputils": "^4.0.0",
-        "@jupyterlab/mainmenu": "^4.0.0",
-        "@jupyterlab/notebook": "^4.0.0",
-        "@jupyterlab/services": "^7.0.0",
-        "@jupyterlab/settingregistry": "^4.0.0",
-        "@jupyterlab/statedb": "^4.0.0",
-        "@jupyterlab/translation": "^4.0.0",
-        "@jupyterlab/ui-components": "^4.0.0",
+        "@jupyterlab/application": "^4.3.0",
+        "@jupyterlab/apputils": "^4.3.0",
+        "@jupyterlab/mainmenu": "^4.3.0",
+        "@jupyterlab/notebook": "^4.3.0",
+        "@jupyterlab/services": "^7.3.0",
+        "@jupyterlab/settingregistry": "^4.3.0",
+        "@jupyterlab/statedb": "^4.3.0",
+        "@jupyterlab/translation": "^4.3.0",
+        "@jupyterlab/ui-components": "^4.3.0",
         "@lumino/coreutils": "^2.1.1",
         "@lumino/disposable": "^2.1.1",
         "@lumino/signaling": "^2.1.1",
-        "@lumino/widgets": "^2.1.1",
-        "ajv": "^8.12.0",
+        "@lumino/widgets": "^2.3.1",
+        "ajv": "^8.17.1",
         "react": "^18.2.0",
-        "react-joyride": "^2.5.5"
+        "react-joyride": "^2.9.3"
     },
     "devDependencies": {
         "@babel/core": "^7.20.12",
         "@babel/preset-env": "^7.20.2",
-        "@jupyterlab/builder": "^4.0.0",
-        "@jupyterlab/testutils": "^4.0.0",
+        "@jupyter/builder": "^1.2.1",
+        "@jupyterlab/testutils": "^4.3.0",
         "@types/jest": "^29.2.0",
         "@types/json-schema": "^7.0.11",
         "@types/react": "^18.0.26",
@@ -93,8 +93,8 @@
         "eslint-plugin-react-hooks": "^4.6.0",
         "jest": "^29.2.0",
         "npm-run-all": "^4.1.5",
-        "prettier": "^3.0.0",
-        "rimraf": "^5.0.1",
+        "prettier": "^3.6.2",
+        "rimraf": "^6.1.2",
         "source-map-loader": "^1.0.2",
         "style-loader": "^3.3.1",
         "stylelint": "^15.10.1",
@@ -102,7 +102,6 @@
         "stylelint-config-standard": "^34.0.0",
         "ts-jest": "^29.1.1",
         "typescript": "~5.0.4",
-        "yarn-berry-deduplicate": "^6.1.1",
         "yjs": "^13.5.40"
     },
     "sideEffects": [
@@ -110,14 +109,25 @@
         "style/index.js"
     ],
     "resolutions": {
-        "@types/node": "^18.0.0",
+        "@types/node": "^22.10.1",
         "@types/react": "^18.0.26",
-        "react": "^18.2.0"
+        "react": "^18.2.0",
+        "yjs": "^13.5.40"
     },
     "jupyterlab": {
         "extension": true,
         "schemaDir": "schema",
-        "outputDir": "jupyterlab_tour/labextension"
+        "outputDir": "jupyterlab_tour/labextension",
+        "sharedPackages": {
+            "ajv": {
+                "bundled": true,
+                "singleton": false
+            },
+            "react-joyride": {
+                "bundled": true,
+                "singleton": false
+            }
+        }
     },
     "styleModule": "style/index.js",
     "eslintIgnore": [
@@ -165,6 +175,13 @@
                     "args": "none"
                 }
             ],
+            "@typescript-eslint/consistent-type-imports": [
+                "error",
+                {
+                    "prefer": "type-imports",
+                    "fixStyle": "separate-type-imports"
+                }
+            ],
             "@typescript-eslint/no-explicit-any": "off",
             "@typescript-eslint/no-namespace": "off",
             "@typescript-eslint/no-use-before-define": "off",
@@ -197,6 +214,13 @@
                 "options": {
                     "tabWidth": 4
                 }
+            },
+            {
+                "files": ".github/workflows/*.yml",
+                "options": {
+                    "proseWrap": "never",
+                    "printWidth": 120
+                }
             }
         ]
     },

package/schema/user-tours.json

@@ -11,7 +11,7 @@
   "properties": {
     "tours": {
       "type": "array",
-      "description": "An array of a tours. Each requires an `id`, `label` and `steps[]`, and may have `options`, see https://docs.react-joyride.com",
+      "description": "An array of tours. Each requires an `id`, `label` and `steps[]`, and may have `options`. For `steps` and `options`, see https://github.com/gilbarbara/react-joyride/blob/v2.9.3/docs/SUMMARY.md",
       "default": [],
       "items": {
         "type": "object",