@rently-team/shepherd.js
Version:
Guide your users through a tour of your app.
661 lines (656 loc) • 19.1 kB
text/typescript
// Generated by dts-bundle-generator v9.5.1
import { ComputePositionConfig, OffsetOptions } from '@floating-ui/dom';
export type Bindings = {
[key: string]: Array<{
handler: () => void;
ctx?: unknown;
once?: boolean;
}>;
};
export type AnyHandler = (...args: any[]) => void;
export declare class Evented {
bindings: Bindings;
/**
* Adds an event listener for the given event string.
*
* @param {string} event
* @param {Function} handler
* @param ctx
* @param {boolean} once
* @returns
*/
on(event: string, handler: AnyHandler, ctx?: unknown, once?: boolean): this;
/**
* Adds an event listener that only fires once for the given event string.
*
* @param {string} event
* @param {Function} handler
* @param ctx
* @returns
*/
once(event: string, handler: AnyHandler, ctx?: unknown): this;
/**
* Removes an event listener for the given event string.
*
* @param {string} event
* @param {Function} handler
* @returns
*/
off(event: string, handler?: AnyHandler): this;
/**
* Triggers an event listener for the given event string.
*
* @param {string} event
* @returns
*/
trigger(event: string, ...args: any[]): this;
}
export type StepText = string | ReadonlyArray<string> | HTMLElement | (() => string | ReadonlyArray<string> | HTMLElement);
export type StringOrStringFunction = string | (() => string);
/**
* The options for the step
*/
export interface StepOptions {
/**
* The element the step should be attached to on the page.
* An object with properties `element` and `on`.
*
* ```js
* const step = new Step(tour, {
* attachTo: { element: '.some .selector-path', on: 'left' },
* ...moreOptions
* });
* ```
*
* If you don’t specify an attachTo the element will appear in the middle of the screen.
* If you omit the `on` portion of `attachTo`, the element will still be highlighted, but the tooltip will appear
* in the middle of the screen, without an arrow pointing to the target.
*/
attachTo?: StepOptionsAttachTo;
/**
* An action on the page which should advance shepherd to the next step.
* It should be an object with a string `selector` and an `event` name
* ```js
* const step = new Step(tour, {
* advanceOn: { selector: '.some .selector-path', event: 'click' },
* ...moreOptions
* });
* ```
* `event` doesn’t have to be an event inside the tour, it can be any event fired on any element on the page.
* You can also always manually advance the Tour by calling `myTour.next()`.
*/
advanceOn?: StepOptionsAdvanceOn;
/**
* Whether to display the arrow for the tooltip or not, or options for the arrow.
*/
arrow?: boolean | StepOptionsArrow;
/**
* A function that returns a promise.
* When the promise resolves, the rest of the `show` code for the step will execute.
*/
beforeShowPromise?: () => Promise<unknown>;
/**
* An array of buttons to add to the step. These will be rendered in a
* footer below the main body text.
*/
buttons?: ReadonlyArray<StepOptionsButton>;
/**
* Should a cancel “✕” be shown in the header of the step?
*/
cancelIcon?: StepOptionsCancelIcon;
/**
* A boolean, that when set to false, will set `pointer-events: none` on the target.
*/
canClickTarget?: boolean;
/**
* A string of extra classes to add to the step's content element.
*/
classes?: string;
/**
* An array of extra element selectors to highlight when the overlay is shown
* The tooltip won't be fixed to these elements, but they will be highlighted
* just like the `attachTo` element.
* ```js
* const step = new Step(tour, {
* extraHighlights: [ '.pricing', '#docs' ],
* ...moreOptions
* });
* ```
*/
extraHighlights?: ReadonlyArray<string>;
/**
* An extra class to apply to the `attachTo` element when it is
* highlighted (that is, when its step is active). You can then target that selector in your CSS.
*/
highlightClass?: string;
/**
* The string to use as the `id` for the step.
*/
id?: string;
/**
* An amount of padding to add around the modal overlay opening
*/
modalOverlayOpeningPadding?: number;
/**
* An amount of border radius to add around the modal overlay opening
*/
modalOverlayOpeningRadius?: number | {
topLeft?: number;
bottomLeft?: number;
bottomRight?: number;
topRight?: number;
};
/**
* An amount to offset the modal overlay opening in the x-direction
*/
modalOverlayOpeningXOffset?: number;
/**
* An amount to offset the modal overlay opening in the y-direction
*/
modalOverlayOpeningYOffset?: number;
/**
* Extra [options to pass to FloatingUI]{@link https://floating-ui.com/docs/tutorial/}
*/
floatingUIOptions?: ComputePositionConfig;
/**
* Should the element be scrolled to when this step is shown?
*/
scrollTo?: boolean | ScrollIntoViewOptions;
/**
* A function that lets you override the default scrollTo behavior and
* define a custom action to do the scrolling, and possibly other logic.
*/
scrollToHandler?: (element: HTMLElement) => void;
/**
* A function that, when it returns `true`, will show the step.
* If it returns `false`, the step will be skipped.
*/
showOn?: () => boolean;
/**
* The text in the body of the step. It can be one of four types:
* ```
* - HTML string
* - Array of HTML strings
* - `HTMLElement` object
* - `Function` to be executed when the step is built. It must return one of the three options above.
* ```
*/
text?: StepText;
/**
* The step's title. It becomes an `h3` at the top of the step.
* ```
* - HTML string
* - `Function` to be executed when the step is built. It must return HTML string.
* ```
*/
title?: StringOrStringFunction;
/**
* The titleIcon will be added ot the header
* ```
* - HTML string
* - `Function` to be executed when the step is built. It must return HTML string.
* ```
*/
titleIcon?: StringOrStringFunction;
/**
* The step's footer. It becomes a span in the footer's beginning.
* ```
* - HTML string
* - `Function` to be executed when the step is built. It must return HTML string.
* ```
*/
footerText?: StringOrStringFunction;
/**
* Doesnt have any impact on the step
*/
pageUrl?: string;
/**
* Doesnt have any impact on the step
*/
static?: boolean;
/**
* You can define `show`, `hide`, etc events inside `when`. For example:
* ```js
* when: {
* show: function() {
* window.scrollTo(0, 0);
* }
* }
* ```
*/
when?: StepOptionsWhen;
/**
* The offset will be used as offset value for the @floating-ui/dom
* It will adjust the position of the popover from the target
* ```
* - OffsetOptions
* ```
*/
offset?: OffsetOptions;
/**
* Configuration for an overlay element positioned over the target element.
*/
overlay?: StepOverlay;
}
export type PopperPlacement = "auto" | "auto-start" | "auto-end" | "top" | "top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end" | "right" | "right-start" | "right-end" | "left" | "left-start" | "left-end";
export interface StepOptionsArrow {
padding?: number;
}
export interface StepOptionsAttachTo {
element?: HTMLElement | string | null | (() => HTMLElement | string | null | undefined);
on?: PopperPlacement;
wait?: number;
strict?: boolean;
}
export interface StepOverlay {
/**
* CSS class applied to the overlay element.
*/
class: string;
/**
* Optional horizontal padding (in pixels) applied around the overlay.
* This affects the size and position of the overlay.
*/
paddingX?: number;
/**
* Optional vertical padding (in pixels) applied around the overlay.
* This affects the size and position of the overlay.
*/
paddingY?: number;
}
export interface StepOptionsAdvanceOn {
event: string;
selector: string;
}
export interface StepOptionsButton {
/**
* A function executed when the button is clicked on
* It is automatically bound to the `tour` the step is associated with, so things like `this.next` will
* work inside the action.
* You can use action to skip steps or navigate to specific steps, with something like:
* ```js
* action() {
* return this.show('some_step_name');
* }
* ```
*/
action?: (this: Tour) => void;
/**
* Extra classes to apply to the `<a>`
*/
classes?: string;
/**
* Whether the button should be disabled
* When the value is `true`, or the function returns `true` the button will be disabled
*/
disabled?: boolean | (() => boolean);
/**
* The aria-label text of the button
*/
label?: StringOrStringFunction;
/**
* A boolean, that when true, adds a `shepherd-button-secondary` class to the button.
*/
secondary?: boolean;
/**
* The HTML text of the button
*/
text?: StringOrStringFunction;
}
export interface StepOptionsButtonEvent {
[key: string]: () => void;
}
export interface StepOptionsCancelIcon {
enabled?: boolean;
label?: string;
}
export interface StepOptionsWhen {
[key: string]: (this: Step) => void;
}
export interface Overlay {
element: HTMLElement;
cleanup?: () => void;
}
/**
* A class representing steps to be added to a tour.
* @extends {Evented}
*/
export declare class Step extends Evented {
_resolvedAttachTo: StepOptionsAttachTo | null;
_resolvedExtraHighlightElements?: HTMLElement[];
classPrefix?: string;
cleanup: Function | null;
el?: HTMLElement | null;
id: string;
options: StepOptions;
target?: HTMLElement | null;
tour: Tour;
observer?: MutationObserver;
_overlay?: Overlay;
advanceEl?: HTMLElement | null;
constructor(tour: Tour, options?: StepOptions);
/**
* Cancel the tour
* Triggers the `cancel` event
*/
cancel(): void;
/**
* Complete the tour
* Triggers the `complete` event
*/
complete(): void;
/**
* Remove the step, delete the step's element, and destroy the FloatingUI instance for the step.
* Triggers `destroy` event
*/
destroy(): void;
/**
* Returns the tour for the step
* @return The tour instance
*/
getTour(): Tour;
/**
* Hide the step
*/
hide(): void;
/**
* Resolves attachTo options.
* @returns {{}|{element, on}}
*/
_resolveExtraHiglightElements(): HTMLElement[];
/**
* Resolves attachTo options.
* @returns {{}|{element, on}}
*/
_resolveAttachToOptions(): StepOptionsAttachTo;
/**
* A selector for resolved attachTo options.
* @returns {{}|{element, on}}
* @private
*/
_getResolvedAttachToOptions(): StepOptionsAttachTo;
/**
* Check if the step is open and visible
* @return True if the step is open and visible
*/
isOpen(): boolean;
_waitForElement(): Promise<unknown>;
/**
* Wraps `_show` and ensures `beforeShowPromise` resolves before calling show
* Wraps `_waitForElement` to wait for the element to appear before showing
*/
show(): Promise<void>;
/**
* Updates the options of the step.
*
* @param {StepOptions} options The options for the step
*/
updateStepOptions(options: StepOptions): void;
/**
* Returns the element for the step
* @return {HTMLElement|null|undefined} The element instance. undefined if it has never been shown, null if it has been destroyed
*/
getElement(): HTMLElement | null | undefined;
/**
* Returns the target for the step
* @return {HTMLElement|null|undefined} The element instance. undefined if it has never been shown, null if query string has not been found
*/
getTarget(): HTMLElement | null | undefined;
/**
* Creates Shepherd element for step based on options
*
* @return {HTMLElement} The DOM element for the step tooltip
* @private
*/
_createTooltipContent(): any;
/**
* If a custom scrollToHandler is defined, call that, otherwise do the generic
* scrollIntoView call.
*
* @param {boolean | ScrollIntoViewOptions} scrollToOptions - If true, uses the default `scrollIntoView`,
* if an object, passes that object as the params to `scrollIntoView` i.e. `{ behavior: 'smooth', block: 'center' }`
* @private
*/
_scrollTo(scrollToOptions: boolean | ScrollIntoViewOptions): void;
/**
* _getClassOptions gets all possible classes for the step
* @param {StepOptions} stepOptions The step specific options
* @returns {string} unique string from array of classes
*/
_getClassOptions(stepOptions: StepOptions): string;
/**
* Sets the options for the step, maps `when` to events, sets up buttons
* @param options - The options for the step
*/
_setOptions(options?: StepOptions): void;
/**
* Creates a overlay element that appears above the target
* @returns HTMLElement
*/
_createOverlay(): HTMLElement;
/**
* Deletes the created overlay element and
* cleanup the autoupdate of its pos
* @returns void
*/
_removeOverlay(): void;
/**
* Create the element and set up the FloatingUI instance
* @private
*/
_setupElements(): void;
/**
* Triggers `before-show`, generates the tooltip DOM content,
* sets up a FloatingUI instance for the tooltip, then triggers `show`.
* @private
*/
_show(trigger?: boolean): void;
/**
* Modulates the styles of the passed step's target element, based on the step's options and
* the tour's `modal` option, to visually emphasize the element
*
* @param {Step} step The step object that attaches to the element
* @private
*/
_styleTargetElementForStep(step: Step): void;
/**
* When a step is hidden, remove the highlightClass and 'shepherd-enabled'
* and 'shepherd-target' classes
* @private
*/
_updateStepTargetOnHide(): void;
}
export interface EventOptions {
previous?: Step | null;
step?: Step | null;
tour: Tour;
}
export type TourConfirmCancel = boolean | (() => boolean) | Promise<boolean> | (() => Promise<boolean>);
/**
* The options for the tour
*/
export interface TourOptions {
/**
* If true, will issue a `window.confirm` before cancelling.
* If it is a function(support Async Function), it will be called and wait for the return value,
* and will only be cancelled if the value returned is true.
*/
confirmCancel?: TourConfirmCancel;
/**
* The message to display in the `window.confirm` dialog.
*/
confirmCancelMessage?: string;
/**
* The prefix to add to the `shepherd-enabled` and `shepherd-target` class names as well as the `data-shepherd-step-id`.
*/
classPrefix?: string;
/**
* Default options for Steps ({@link Step#constructor}), created through `addStep`.
*/
defaultStepOptions?: StepOptions;
/**
* Exiting the tour with the escape key will be enabled unless this is explicitly
* set to false.
*/
exitOnEsc?: boolean;
/**
* Explicitly set the id for the tour. If not set, the id will be a generated uuid.
*/
id?: string;
/**
* Navigating the tour via left and right arrow keys will be enabled
* unless this is explicitly set to false.
*/
keyboardNavigation?: boolean;
/**
* An optional container element for the modal.
* If not set, the modal will be appended to `document.body`.
*/
modalContainer?: HTMLElement;
/**
* An optional container element for the steps.
* If not set, the steps will be appended to `document.body`.
*/
stepsContainer?: HTMLElement;
/**
* An array of step options objects or Step instances to initialize the tour with.
*/
steps?: Array<StepOptions> | Array<Step>;
/**
* An optional "name" for the tour. This will be appended to the the tour's
* dynamically generated `id` property.
*/
tourName?: string;
/**
* Whether or not steps should be placed above a darkened
* modal overlay. If true, the overlay will create an opening around the target element so that it
* can remain interactive
*/
useModalOverlay?: boolean;
}
export declare class ShepherdBase extends Evented {
activeTour?: Tour | null;
Step: typeof Step;
Tour: typeof Tour;
constructor();
}
/**
* Class representing the site tour
* @extends {Evented}
*/
export declare class Tour extends Evented {
trackedEvents: string[];
classPrefix: string;
currentStep?: Step | null;
focusedElBeforeOpen?: HTMLElement | null;
id?: string;
modal?: any | null;
options: TourOptions;
steps: Array<Step>;
constructor(options?: TourOptions);
/**
* Adds a new step to the tour
* @param {StepOptions} options - An object containing step options or a Step instance
* @param {number | undefined} index - The optional index to insert the step at. If undefined, the step
* is added to the end of the array.
* @return The newly added step
*/
addStep(options: StepOptions | Step, index?: number): Step | StepOptions;
/**
* Add multiple steps to the tour
* @param {Array<StepOptions> | Array<Step> | undefined} steps - The steps to add to the tour
*/
addSteps(steps?: Array<StepOptions> | Array<Step>): this;
/**
* Go to the previous step in the tour
*/
back(): void;
/**
* Calls _done() triggering the 'cancel' event
* If `confirmCancel` is true, will show a window.confirm before cancelling
* If `confirmCancel` is a function, will call it and wait for the return value,
* and only cancel when the value returned is true
*/
cancel(): Promise<void>;
/**
* Calls _done() triggering the `complete` event
*/
complete(): void;
/**
* Gets the step from a given id
* @param {number | string} id - The id of the step to retrieve
* @return The step corresponding to the `id`
*/
getById(id: number | string): Step | undefined;
/**
* Gets the current step
*/
getCurrentStep(): Step | null | undefined;
/**
* Hide the current step
*/
hide(): void;
/**
* Check if the tour is active
*/
isActive(): boolean;
/**
* Go to the next step in the tour
* If we are at the end, call `complete`
*/
next(): void;
/**
* Removes the step from the tour
* @param {string} name - The id for the step to remove
*/
removeStep(name: string): void;
/**
* Show a specific step in the tour
* @param {number | string} key - The key to look up the step by
* @param {boolean} forward - True if we are going forward, false if backward
*/
show(key?: number | string, forward?: boolean): void;
/**
* Start the tour
*/
start(): Promise<void>;
/**
* Called whenever the tour is cancelled or completed, basically anytime we exit the tour
* @param {string} event - The event name to trigger
* @private
*/
_done(event: string): void;
/**
* Make this tour "active"
*/
_setupActiveTour(): void;
/**
* setupModal create the modal container and instance
*/
setupModal(): void;
/**
* Called when `showOn` evaluates to false, to skip the step or complete the tour if it's the last step
* @param {Step} step - The step to skip
* @param {boolean} forward - True if we are going forward, false if backward
* @private
*/
_skipStep(step: Step, forward: boolean): void;
/**
* Before showing, hide the current step and if the tour is not
* already active, call `this._setupActiveTour`.
* @private
*/
_updateStateBeforeShow(): void;
/**
* Sets this.id to a provided tourName and id or `${tourName}--${uuid}`
* @param {string} optionsId - True if we are going forward, false if backward
* @private
*/
_setTourID(optionsId: string | undefined): void;
}
/**
* @public
*/
export declare const Shepherd: ShepherdBase;
export = Shepherd;
export {};