diff --git a/source/tours/exports.ts b/source/tours/exports.ts index 9c25b24..8441070 100644 --- a/source/tours/exports.ts +++ b/source/tours/exports.ts @@ -6,6 +6,7 @@ export * from "./introduction.js"; export * from "./shared/exports.js"; export * from "./types.js"; +/** All tours available in a single array. */ export const allTours: TourData[] = [ introductionTour, accountSettingsTour, diff --git a/source/tours/shared/logged-out-warning.tsx b/source/tours/shared/logged-out-warning.tsx index 9717f82..81cb44c 100644 --- a/source/tours/shared/logged-out-warning.tsx +++ b/source/tours/shared/logged-out-warning.tsx @@ -1,5 +1,6 @@ import {type JSX} from "preact"; +/** Check if the user is logged in and return a warning element if they aren't. */ export function LoggedOutWarning(): JSX.Element { const userIsLoggedIn = document.querySelector(".logged-in-user-username") !== null; diff --git a/source/tours/shared/tour-error.tsx b/source/tours/shared/tour-error.tsx index 0f9bcb6..e4ad4be 100644 --- a/source/tours/shared/tour-error.tsx +++ b/source/tours/shared/tour-error.tsx @@ -1,6 +1,10 @@ import Shepherd from "shepherd.js"; import {renderInContainer} from "../utilities.js"; +/** + * Start an ad-hoc tour to display an error message. + * @param text The message to show. + */ export function showTourError(text: string) { const tour = new Shepherd.Tour({ defaultStepOptions: { diff --git a/source/tours/types.ts b/source/tours/types.ts index 2702204..b6e6ff5 100644 --- a/source/tours/types.ts +++ b/source/tours/types.ts @@ -1,30 +1,58 @@ import type Shepherd from "shepherd.js"; +/** All available tour IDs. */ export enum TourId { InterfaceAccountSettings = "interface-account-settings", InterfaceHomepage = "interface-homepage", Introduction = "introduction", } +/** Requirements of a tour to be checked before the tour is started. */ export type TourRequirement = { + /** + * This tour requires that the user must be logged in. Only set this to true + * if the tour goes to pages only accessible by logged in users. + */ mustBeLoggedIn: boolean; + + /** The {@link URL.pathname} to run the tour at. */ path: string; }; +/** An individual tour step event handler. */ export type TourStepEvent = { + /** + * - The "show" event will be called when the step is displayed. + * - The "destroy" event will be called when the step is finished. + */ event: "show" | "destroy"; + /** The handler for this step event. */ handler: Parameters[1]; }; +/** All the tour data collected in one place. */ export type TourData = { + /** A short description of the tour for use in the options page. */ description: string; + + /** Whether this tour should be shown in the options page. */ displayInOptionsPage: boolean; + + /** All event handlers to be added to this tour's steps. */ eventHandlers: Array<{ eventHandlers: TourStepEvent[]; stepId: string; }>; + + /** The unique ID for this tour. */ id: TourId; + + /** The requirements this tour must match before starting it. */ requirements: TourRequirement; + + /** All the steps this tour will take. */ steps: Shepherd.Step.StepOptions[]; + + /** The title of the tour for use in the options page. */ title: string; }; diff --git a/source/tours/utilities.ts b/source/tours/utilities.ts index 331f009..2735936 100644 --- a/source/tours/utilities.ts +++ b/source/tours/utilities.ts @@ -5,7 +5,7 @@ import browser from "webextension-polyfill"; * Adds a `[data-tildes-shepherd-counter]` attribute to a specified element. For * the associated CSS, see `source/content-scripts/scss/main.scss`. * - * @param selector The selector of element to apply the counter to, if the + * @param selector The selector of the element to apply the counter to, if the * target element can't be selected an error will be thrown. * @param count The number to display in the counter. */