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..b86b566cf 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,8 @@ + +/** + * An API for Tour Guide + * @namespace RED.tourGuide +*/ RED.tourGuide = (function() { var activeListeners = []; var shade; @@ -7,8 +12,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 +41,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 +97,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 +167,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 +196,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 +233,7 @@ RED.tourGuide = (function() { finish(); } + function getLocaleText(property) { if (typeof property === 'string') { return property; @@ -199,6 +243,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() {