Documents and types the RED.tourGuide API

packages/node_modules/@node-red/editor-client/src/js/ui/tour/tourGuide.js

@@ -1,3 +1,23 @@
+/**
+ * Copyright JS Foundation and other contributors, http://js.foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+
+/**
+ * An API for Tour Guide
+ * @namespace RED.tourGuide
+*/
 RED.tourGuide = (function() {
     var activeListeners = [];
     var shade;
@@ -7,8 +27,19 @@ RED.tourGuide = (function() {
     var targetElement;
     var fullscreen;
 
+    /**
+     * @type {Record<string, Tour>}
+     */
     var tourCache = {};
 
+    /**
+     * Run a Tour Guide.
+     * Starts by importing it if it has not been loaded.
+     *
+     * @param {string} tourPath The path to the tour file
+     * @param {(error?: Error) => void} [done] A function called
+     * when the guide is finished/closed
+     */
     function run(tourPath, done) {
         done = done || function(err) {
             if (err) {
@@ -25,6 +56,13 @@ RED.tourGuide = (function() {
 
     }
 
+    /**
+     * Load a Tour Guide.
+     *
+     * @param {string} tourPath The path to the tour file
+     * @param {(error: Error | null, tour?: Tour) => void} done A function
+     * called when the guide is loaded or an error has occurred
+     */
     function loadTour(tourPath, done) {
         if (tourCache[tourPath]) {
             done(null, tourCache[tourPath]);
@@ -74,6 +112,13 @@ RED.tourGuide = (function() {
             }
         }
     }
+
+    /**
+     * @typedef {{version: string; steps: Array<TourStep>}} Tour
+     *
+     * @param {Tour} tour 
+     * @param {(error?: Error) => void} done 
+     */
     function runTour(tour, done) {
 
         shade = $('<div class="red-ui-tourGuide-shade"></div>').appendTo(document.body);
@@ -137,6 +182,12 @@ RED.tourGuide = (function() {
         activeListeners = [];
     }
 
+    /**
+     * @param {TourStep} step 
+     * @param {TourStepState} state 
+     * @param {() => void} done 
+     * @returns {void}
+     */
     function prepareStep(step, state, done) {
         if (step.prepare) {
             if (step.prepare.length === 0) {
@@ -160,6 +211,13 @@ RED.tourGuide = (function() {
         }
         done();
     }
+
+    /**
+     * @param {TourStep} step 
+     * @param {TourStepState} state 
+     * @param {() => void} done 
+     * @returns {void}
+     */
     function completeStep(step, state, done) {
         function finish() {
             clearListeners();
@@ -190,6 +248,7 @@ RED.tourGuide = (function() {
         finish();
 
     }
+
     function getLocaleText(property) {
         if (typeof property === 'string') {
             return property;
@@ -199,6 +258,51 @@ RED.tourGuide = (function() {
         return property[currentLang]||property['en-US']||property[availableLangs[0]]
 
     }
+
+    /**
+     * @typedef {"right"|"left"|"bottom"|"top"|"inset"} Direction A valid CSS
+     * direction. The list is not exhaustive.
+     *
+     * @typedef {object} TourStepState
+     * @property {number} index The index of the current step
+     * @property {number} count The total number of steps
+     * 
+     * @typedef {object} Wait
+     * @property {"dom-event"|"nr-event"} type The emitter type. If `dom-event`
+     * use {@link Wait.element element} otherwise use {@link Wait.filter filter}
+     * @property {string} event The event name
+     * @property {string|((this: TourStepState) => JQuery)} element The DOM
+     * element to attach the event listener
+     * @property {(event: object) => boolean} filter An function called when
+     * the event is triggered to filter the target action.
+     *
+     * @typedef {object} TourStep Represents a step of the Tour Guide
+     * @property {(this: TourStepState, done?: () => void) => void} [complete]
+     * A function called when the dialog is being closed
+     * @property {string} [description] The description of the dialog
+     * @property {Direction} [direction = "bottom"] The direction of the dialog
+     * relative to the {@link TourStep.element element}. Default `bottom`.
+     * @property {string|JQuery|((this: TourStepState) => JQuery)} [element]
+     * The DOM element to highlight.
+     * @property {Direction} [fallback] On mouse hover, stop highlighting the 
+     * {@link TourStep.element element} and move the dialog in another direction
+     * @property {string} [image] The path to the image to be integrated into
+     * the dialog
+     * @property {boolean} [interactive] Either to place the dialog on top of
+     * the overlapping stack. Enabled if {@link TourStep.wait wait} is used
+     * @property {(this: TourStepState, done?: () => void) => void} [prepare]
+     * A function called when the dialog is being built
+     * @property {string} [title] The title of the dialog
+     * @property {string} [titleIcon] The icon to add to the title in the dialog
+     * @property {Wait} [wait] Wait for an event to be triggered before closing
+     * the dialog
+     * @property {string|number} [width] The width of the dialog
+     *
+     * @param {TourStep} step A step of the Tour Guide
+     * @param {TourStepState} state The state of a the Tour Guide step
+     * @param {() => void} done A function called when the dialog is closed.
+     * After the {@link TourStep.complete complete} event
+     */
     function runTourStep(step, state, done) {
         shade.fadeIn();
         prepareStep(step, state, function() {