Enhance tour version (#81)

* Hide empty value for select

* Use config to preserve tour states

* Fix code and tests

Author: fcollonval

package.json

@@ -62,6 +62,7 @@
         "@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",

schema/user-tours.json

@@ -46,6 +46,12 @@
             "description": "Other options for the tour",
             "$ref": "#/definitions/Props"
           },
+          "version": {
+            "type": "integer",
+            "title": "The tour version",
+            "description": "The tour version (prefer calendar versioning YYYYMMDD) to determine if an user should see it again or not.",
+            "minimum": 0
+          },
           "translation": {
             "description": "Translation domain containing strings for this tour",
             "type": "string"

src/__tests__/plugin.spec.ts

@@ -6,7 +6,6 @@ import {
   NotebookPanel
 } from '@jupyterlab/notebook';
 import { ISettingRegistry } from '@jupyterlab/settingregistry';
-import { StateDB } from '@jupyterlab/statedb';
 import { CommandRegistry } from '@lumino/commands';
 import { ReadonlyJSONObject } from '@lumino/coreutils';
 import { DocumentRegistry } from '@jupyterlab/docregistry';
@@ -90,8 +89,7 @@ describe(corePlugin.id, () => {
   describe('activation', () => {
     it('should create add-tour command', () => {
       const app = mockApp();
-      const stateDB = new StateDB();
-      corePlugin.activate(app as any, stateDB);
+      corePlugin.activate(app as any);
 
       expect(app.commands?.hasCommand(CommandIDs.addTour)).toEqual(true);
     });
@@ -101,8 +99,7 @@ describe(corePlugin.id, () => {
     describe(`${CommandIDs.addTour}`, () => {
       it('should add a tour command', async () => {
         const app = mockApp();
-        const stateDB = new StateDB();
-        const manager = corePlugin.activate(app as any, stateDB) as ITourManager;
+        const manager = corePlugin.activate(app as any) as ITourManager;
         expect(manager.tours.size).toEqual(0);
 
         const tour = await app.commands?.execute(CommandIDs.addTour, {
@@ -121,8 +118,7 @@ describe(userPlugin.id, () => {
   describe('activation', () => {
     it('should have userTours', async () => {
       const app = mockApp();
-      const stateDB = new StateDB();
-      const manager = corePlugin.activate(app as any, stateDB) as ITourManager;
+      const manager = corePlugin.activate(app as any) as ITourManager;
       const settings = mockSettingRegistry();
       const userManager = userPlugin.activate(
         app as any,
@@ -137,8 +133,7 @@ describe(userPlugin.id, () => {
   describe('settings', () => {
     it('should react to settings', async () => {
       const app = mockApp();
-      const stateDB = new StateDB();
-      const manager = corePlugin.activate(app as any, stateDB) as ITourManager;
+      const manager = corePlugin.activate(app as any) as ITourManager;
       const settingsRegistry = mockSettingRegistry();
       const userManager = userPlugin.activate(
         app as any,
@@ -158,8 +153,7 @@ describe(notebookPlugin.id, () => {
   describe('activation', () => {
     it('should activate', async () => {
       const app = mockApp();
-      const stateDB = new StateDB();
-      const manager = corePlugin.activate(app as any, stateDB) as ITourManager;
+      const manager = corePlugin.activate(app as any) as ITourManager;
       const nbTracker = mockNbTracker();
       const notebookTourManager = notebookPlugin.activate(
         app as any,
@@ -195,8 +189,7 @@ describe(defaultsPlugin.id, () => {
   describe('activation', () => {
     it('should activate', () => {
       const app = mockApp();
-      const stateDB = new StateDB();
-      const manager = corePlugin.activate(app as any, stateDB) as ITourManager;
+      const manager = corePlugin.activate(app as any) as ITourManager;
       defaultsPlugin.activate(app as any, manager);
       expect(manager.tours.size).toEqual(DEFAULT_TOURS_SIZE);
     });

src/defaults.tsx

@@ -23,13 +23,13 @@ namespace DefaultTours {
     ): void {
       const trans = manager.translator;
 
-      const welcomeTour = manager.createTour(
-        WELCOME_ID,
-        trans.__('Welcome Tour'),
-        true,
-        undefined,
-        defaultTourIcon
-      );
+      const welcomeTour = manager.createTour({
+        id: WELCOME_ID,
+        label: trans.__('Welcome Tour'),
+        hasHelpEntry: true,
+        icon: defaultTourIcon,
+        version: 20231107
+      });
 
       welcomeTour.options = {
         ...welcomeTour.options,
@@ -292,13 +292,13 @@ namespace DefaultTours {
       appName = 'JupyterLab'
     ): void {
       const trans = manager.translator;
-      const notebookTour = manager.createTour(
-        NOTEBOOK_ID,
-        trans.__('Notebook Tour'),
-        true,
-        undefined,
-        defaultNotebookTourIcon
-      );
+      const notebookTour = manager.createTour({
+        id: NOTEBOOK_ID,
+        label: trans.__('Notebook Tour'),
+        hasHelpEntry: true,
+        icon: defaultNotebookTourIcon,
+        version: 20231107
+      });
 
       notebookTour.options = {
         ...notebookTour.options,
@@ -541,11 +541,12 @@ namespace DefaultTours {
     ): void {
       const trans = manager.translator;
 
-      const welcomeTour = manager.createTour(
-        WELCOME_ID,
-        trans.__('Welcome Tour'),
-        true
-      );
+      const welcomeTour = manager.createTour({
+        id: WELCOME_ID,
+        label: trans.__('Welcome Tour'),
+        hasHelpEntry: true,
+        version: 20231107
+      });
 
       welcomeTour.options = {
         ...welcomeTour.options,

src/notebookButton.tsx

@@ -56,7 +56,7 @@ export class TourButton extends ReactWidget {
         title={title}
         value=""
       >
-        <option value=""></option>
+        <option style={{ display: 'none' }} value=""></option>
         {errors.length ? (
           <option>
             {trans.__('Tour metadata is not valid: see the browser console!')}

src/plugin.tsx

@@ -8,7 +8,7 @@ import {
 import { IMainMenu, MainMenu } from '@jupyterlab/mainmenu';
 import { INotebookTracker, NotebookPanel } from '@jupyterlab/notebook';
 import { ISettingRegistry } from '@jupyterlab/settingregistry';
-import { IStateDB } from '@jupyterlab/statedb';
+import { ConfigSection } from '@jupyterlab/services';
 import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 
 import { Widget } from '@lumino/widgets';
@@ -24,6 +24,8 @@ import {
   INotebookTourManager,
   ITourHandler,
   ITourManager,
+  ITourState,
+  ITourTracker,
   IUserTourManager,
   NOTEBOOK_PLUGIN_ID,
   NS,
@@ -33,6 +35,7 @@ import {
 import { TourHandler } from './tour';
 import { TourManager } from './tourManager';
 import { UserTourManager } from './userTourManager';
+import { PromiseDelegate } from '@lumino/coreutils';
 
 /**
  * Initialization data for the jupyterlab-tour extension.
@@ -41,24 +44,50 @@ const corePlugin: JupyterFrontEndPlugin<ITourManager> = {
   id: PLUGIN_ID,
   autoStart: true,
   activate,
-  requires: [IStateDB],
   optional: [ICommandPalette, IMainMenu, ITranslator],
   provides: ITourManager
 };
 
 function activate(
   app: JupyterFrontEnd,
-  stateDB: IStateDB,
-  palette?: ICommandPalette,
-  menu?: MainMenu,
-  translator?: ITranslator
+  palette: ICommandPalette | null,
+  menu: MainMenu | null,
+  translator: ITranslator | null
 ): ITourManager {
+  const CONFIG_SECTION_NAME = corePlugin.id.replace(/[^\w]/g, '');
   const { commands } = app;
 
   translator = translator ?? nullTranslator;
 
+  const restoreState = new PromiseDelegate<ITourState[]>();
+  const configReady = ConfigSection.create({
+    name: CONFIG_SECTION_NAME
+  }).catch(error => {
+    console.error('Failed to fetch state for jupyterlab-tour.', error);
+  });
+  const tracker: ITourTracker = Object.freeze({
+    restored: restoreState.promise,
+    save: async (state: ITourState[]) => {
+      await restoreState.promise;
+      (await configReady)?.update({ state } as any);
+    }
+  });
+
   // Create tour manager
-  const manager = new TourManager(stateDB, translator, menu);
+  const manager = new TourManager({ helpMenu: menu?.helpMenu, tracker, translator });
+  void Promise.all([
+    app.restored,
+    // Use config instead of state to store independently of the workspace
+    // if a tour has been displayed or not.
+    configReady
+  ])
+    .then(async ([_, config]) => {
+      restoreState.resolve((config?.data['state'] ?? []) as any);
+    })
+    .catch(error => {
+      console.error('Failed to load tour states.', error);
+      restoreState.reject(error);
+    });
   const trans = manager.translator;
 
   commands.addCommand(CommandIDs.launch, {
@@ -93,6 +122,8 @@ function activate(
         }
       }
 
+      await manager.ready;
+
       manager.launch([id], force);
     }
   });
@@ -212,7 +243,7 @@ function activateDefaults(
     });
   }
 
-  app.restored.then(() => {
+  Promise.all([app.restored, tourManager.ready]).then(() => {
     if (
       tourManager.tours.has(WELCOME_ID) &&
       (app.name !== 'Jupyter Notebook' ||