diff --git a/packages/node_modules/@node-red/editor-client/src/js/ui/tour/tourGuide.js b/packages/node_modules/@node-red/editor-client/src/js/ui/tour/tourGuide.js index 5ae66720c..c71cd940a 100644 --- a/packages/node_modules/@node-red/editor-client/src/js/ui/tour/tourGuide.js +++ b/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} + */ 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}} Tour + * + * @param {Tour} tour + * @param {(error?: Error) => void} done + */ function runTour(tour, done) { shade = $('
').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() {