source/content-scripts/setup.ts

@@ -1,17 +1,14 @@
 import Shepherd from "shepherd.js";
-import {fromStorage, StorageKey} from "../storage/common.js";
 import {
-  allTours,
-  introductionTour,
-  showTourError,
-  type TourData,
-} from "../tours/exports.js";
+  addCompletedTour,
+  createIntroductionUnderstood,
+} from "../storage/common.js";
+import {introductionSteps} from "../tours/introduction.js";
+import {TourId, tourIdsAndSteps} from "../tours/exports.js";
 
 /** The main entry point for the content script. */
 async function main(): Promise<void> {
-  const introductionUnderstood = await fromStorage(
-    StorageKey.IntroductionUnderstood,
-  );
+  const introductionUnderstood = await createIntroductionUnderstood();
 
   // Get the anchor without the leading #.
   const anchor = window.location.hash.slice(1);
@@ -29,7 +26,9 @@ async function main(): Promise<void> {
     // If a different tour is selected but the introduction hasn't happened yet,
     // then the main function will be rerun once this tour finishes.
     startTour(
-      introductionTour,
+      TourId.Introduction,
+      introductionSteps,
+      [],
       startsWithPrefix && anchorTourId !== "introduction",
     );
     return;
@@ -39,29 +38,11 @@ async function main(): Promise<void> {
     return;
   }
 
-  const userIsLoggedIn =
-    document.querySelector(".logged-in-user-username") !== null;
-
   // Then run through all of the tours we have and start the first match for the
   // ID.
-  for (const tour of allTours) {
-    if (anchorTourId === tour.id) {
-      if (tour.requirements.mustBeLoggedIn && !userIsLoggedIn) {
-        showTourError(
-          `The ${tour.id} tour can only be shown with a logged in account.`,
-        );
-        return;
-      }
-
-      if (tour.requirements.path !== window.location.pathname) {
-        // This tour's path requirement does not match.
-        showTourError(
-          `The ${tour.id} tour can only be start on the ${tour.requirements.path} page.`,
-        );
-        return;
-      }
-
-      startTour(tour, false);
+  for (const [id, steps, eventHandlers] of tourIdsAndSteps) {
+    if (anchorTourId === id) {
+      startTour(id, steps, eventHandlers, false);
       return;
     }
   }
@@ -77,7 +58,12 @@ async function main(): Promise<void> {
  * @param runMainAgainAfterComplete Should the `main` function be run after this
  * tour is completed?
  */
-function startTour(data: TourData, runMainAgainAfterComplete: boolean): void {
+function startTour(
+  tourId: TourId,
+  steps: TourStepOptions[],
+  eventHandlers: TourStepEventHandler[],
+  runMainAgainAfterComplete: boolean,
+): void {
   const defaultButtons: Shepherd.Step.StepOptionsButton[] = [
     {
       classes: "btn",
@@ -120,9 +106,7 @@ function startTour(data: TourData, runMainAgainAfterComplete: boolean): void {
     }
 
     // Mark the tour as completed.
-    const completedTours = await fromStorage(StorageKey.ToursCompleted);
-    completedTours.value.add(data.id);
-    await completedTours.save();
+    await addCompletedTour(tourId);
 
     if (runMainAgainAfterComplete) {
       await main();
@@ -131,24 +115,19 @@ function startTour(data: TourData, runMainAgainAfterComplete: boolean): void {
 
   // For every step we have, add it to the tour and subsequently add all the
   // event handlers to that step.
-  for (const [stepNumber, stepOptions] of data.steps.entries()) {
+  for (const [stepNumber, stepOptions] of steps.entries()) {
     // If the final step doesn't have buttons defined, set the "Continue" button
     // text to "Finish".
-    if (
-      stepOptions.buttons === undefined &&
-      stepNumber + 1 === data.steps.length
-    ) {
+    if (stepOptions.buttons === undefined && stepNumber + 1 === steps.length) {
       stepOptions.buttons = [...defaultButtons];
       stepOptions.buttons[0].text = "Finish";
     }
 
     const step = tour.addStep(stepOptions);
 
-    for (const {stepId, eventHandlers} of data.eventHandlers) {
-      if (stepId === step.id) {
-        for (const {event, handler} of eventHandlers) {
-          step.on(event, handler);
-        }
+    for (const [targetStepId, [eventName, eventHandler]] of eventHandlers) {
+      if (targetStepId === step.id) {
+        step.on(eventName, eventHandler);
       }
     }
   }

source/options/components/tour.tsx

@@ -1,22 +1,59 @@
-import {Component} from "preact";
-import {type TourData} from "../../tours/exports.js";
+import {Component, type JSX} from "preact";
+import {TourId} from "../../tours/exports.js";
 
 type Props = {
   hasBeenCompleted: boolean;
-  tour: TourData;
+  name: string;
+  tourId: TourId;
 };
 
-function tourLink(tour: TourData): string {
-  const anchor = `#tildes-shepherd-tour=${tour.id}`;
+function tourDescription(tourId: Props["tourId"]): JSX.Element {
+  if (tourId === TourId.Introduction) {
+    return (
+      <p class="tour-description">
+        A short introduction to Tildes Shepherd and how the tours work. Normally
+        this is automatically shown when you first installed the extension.
+      </p>
+    );
+  }
+
+  if (tourId === TourId.InterfaceHomepage) {
+    return (
+      <p class="tour-description">
+        Let's take a look at the home page and all we can do there.
+      </p>
+    );
+  }
+
+  return (
+    <p class="tour-description">
+      Tour ID "{tourId}" does not have a description, this should probably be
+      fixed!
+    </p>
+  );
+}
+
+function tourLink(tourId: Props["tourId"]): string {
+  const anchor = `#tildes-shepherd-tour=${tourId}`;
   const baseUrl = "https://tildes.net";
-  const path = tour.requirements.path;
+  let path = "";
+
+  switch (tourId) {
+    case TourId.InterfaceHomepage:
+    case TourId.Introduction: {
+      path = "/";
+      break;
+    }
+
+    default:
+  }
 
   return `${baseUrl}${path}${anchor}`;
 }
 
 export class Tour extends Component<Props> {
   render() {
-    const {hasBeenCompleted, tour} = this.props;
+    const {hasBeenCompleted, name, tourId} = this.props;
     const classes = ["tour", hasBeenCompleted ? "completed" : ""].join(" ");
     const completed = hasBeenCompleted ? (
       <p class="tour-completed" title="You've completed this tour before!">
@@ -26,11 +63,11 @@ export class Tour extends Component<Props> {
 
     return (
       <div class={classes.trim()}>
-        <h3>{tour.title}</h3>
+        <h3>{name}</h3>
         {completed}
-        {tour.description}
+        {tourDescription(tourId)}
         <p class="tour-link">
-          <a href={tourLink(tour)}>Take this tour</a>
+          <a href={tourLink(tourId)}>Take this tour</a>
         </p>
       </div>
     );

source/options/components/tours.tsx

@@ -1,16 +1,12 @@
 import {Component, type JSX} from "preact";
-import {
-  fromStorage,
-  StorageKey,
-  type StorageValues,
-} from "../../storage/common.js";
-import {allTours} from "../../tours/exports.js";
+import {createToursCompleted} from "../../storage/common.js";
+import {TourId} from "../../tours/exports.js";
 import {Tour} from "./tour.js";
 
 type Props = Record<string, unknown>;
 
 type State = {
-  toursCompleted: Awaited<StorageValues[StorageKey.ToursCompleted]>;
+  toursCompleted: Awaited<ReturnType<typeof createToursCompleted>>["value"];
 };
 
 export class Tours extends Component<Props, State> {
@@ -18,29 +14,39 @@ export class Tours extends Component<Props, State> {
     super(props);
 
     this.state = {
-      toursCompleted: undefined!,
+      toursCompleted: new Set(),
     };
   }
 
   async componentDidMount(): Promise<void> {
-    const toursCompleted = await fromStorage(StorageKey.ToursCompleted);
-    this.setState({toursCompleted});
+    const toursCompleted = await createToursCompleted();
+    this.setState({toursCompleted: toursCompleted.value});
   }
 
   render(): JSX.Element {
     const {toursCompleted} = this.state;
-    if (toursCompleted === undefined) {
-      return <></>;
-    }
 
-    const tours = allTours.map((tour) => (
-      <Tour hasBeenCompleted={toursCompleted.value.has(tour.id)} tour={tour} />
-    ));
+    const createTour = (tourId: TourId, name: string): Tour["props"] => {
+      return {
+        hasBeenCompleted: toursCompleted.has(tourId),
+        name,
+        tourId,
+      };
+    };
+
+    const tourProps: Array<Tour["props"]> = [
+      createTour(TourId.Introduction, "Introduction"),
+      createTour(TourId.InterfaceHomepage, "The Homepage"),
+    ];
 
     return (
       <main>
         <h2>Tours</h2>
-        <div class="tours">{tours}</div>
+        <div class="tours">
+          {tourProps.map((props) => (
+            <Tour {...props} />
+          ))}
+        </div>
       </main>
     );
   }

source/storage/common.ts

@@ -2,39 +2,33 @@ import browser from "webextension-polyfill";
 import {createValue} from "@holllo/webextension-storage";
 import {type TourId} from "../tours/exports.js";
 
-/** All available storage keys. */
 export enum StorageKey {
   IntroductionUnderstood = "introduction-understood",
   ToursCompleted = "tours-completed",
 }
 
-/** All values we want to save in storage. */
-const storageValues = {
-  [StorageKey.IntroductionUnderstood]: createValue<boolean>({
+export async function createIntroductionUnderstood() {
+  return createValue<boolean>({
     deserialize: (input) => input === "true",
     serialize: (input) => JSON.stringify(input),
     key: StorageKey.IntroductionUnderstood,
     storage: browser.storage.local,
     value: false,
-  }),
-  [StorageKey.ToursCompleted]: createValue<Set<TourId>>({
+  });
+}
+
+export async function createToursCompleted() {
+  return createValue<Set<TourId>>({
     deserialize: (input) => new Set(JSON.parse(input) as TourId[]),
     serialize: (input) => JSON.stringify(Array.from(input)),
     key: StorageKey.ToursCompleted,
     storage: browser.storage.local,
     value: new Set([]),
-  }),
-};
-
-/** Alias to get the inferred type shape of {@link storageValues}. */
-export type StorageValues = typeof storageValues;
-
-/**
- * Get the stored value for a given key.
- * @param key The key to get from storage.
- */
-export async function fromStorage<K extends StorageKey>(
-  key: K,
-): Promise<StorageValues[K]> {
-  return storageValues[key];
+  });
+}
+
+export async function addCompletedTour(tourId: TourId): Promise<void> {
+  const toursCompleted = await createToursCompleted();
+  toursCompleted.value.add(tourId);
+  await toursCompleted.save();
 }

source/tours/exports.ts

@@ -1,14 +1,14 @@
-import {accountSettingsTour, homepageTour} from "./interface/exports.js";
-import {introductionTour} from "./introduction.js";
-import {type TourData} from "./types.js";
+import {homepageEventHandlers, homepageSteps} from "./interface/exports.js";
+import {introductionSteps} from "./introduction.js";
 
-export * from "./introduction.js";
-export * from "./shared/exports.js";
-export * from "./types.js";
+export enum TourId {
+  InterfaceHomepage = "interface-homepage",
+  Introduction = "introduction",
+}
 
-/** All tours available in a single array. */
-export const allTours: TourData[] = [
-  introductionTour,
-  accountSettingsTour,
-  homepageTour,
+export const tourIdsAndSteps: Array<
+  [TourId, TourStepOptions[], TourStepEventHandler[]]
+> = [
+  [TourId.Introduction, introductionSteps, []],
+  [TourId.InterfaceHomepage, homepageSteps, homepageEventHandlers],
 ];

source/tours/interface/account-settings.tsx

@@ -1,32 +0,0 @@
-import {type TourData, TourId} from "../types.js";
-import {renderInContainer} from "../utilities.js";
-
-const step01 = renderInContainer(
-  <>
-    <h1>Your Account Settings</h1>
-  </>,
-);
-
-const steps: TourData["steps"] = [
-  {
-    id: "account-settings-01",
-    text: step01,
-  },
-];
-
-const eventHandlers: TourData["eventHandlers"] = [];
-
-const requirements: TourData["requirements"] = {
-  mustBeLoggedIn: true,
-  path: "/settings",
-};
-
-export const accountSettingsTour: TourData = {
-  id: TourId.InterfaceAccountSettings,
-  title: "Your Account Settings",
-  description: "View your account settings and all that you can customize.",
-  displayInOptionsPage: true,
-  eventHandlers,
-  requirements,
-  steps,
-};

source/tours/interface/exports.ts

@@ -1,2 +1,4 @@
-export * from "./account-settings.js";
-export * from "./homepage.js";
+export {
+  eventHandlers as homepageEventHandlers,
+  steps as homepageSteps,
+} from "./homepage.js";

source/tours/interface/homepage.tsx

@@ -1,11 +1,11 @@
-import {LoggedOutWarning} from "../shared/logged-out-warning.js";
-import {type TourData, TourId} from "../types.js";
+import type Shepherd from "shepherd.js";
 import {
   addDatasetCounter,
   encapsulateElements,
   removeAllDatasetCounters,
   renderInContainer,
 } from "../utilities.js";
+import {LoggedOutWarning} from "../shared/logged-out-warning.js";
 
 const step01 = renderInContainer(
   <>
@@ -345,7 +345,7 @@ const step10 = renderInContainer(
   </>,
 );
 
-const steps: TourData["steps"] = [
+export const steps: Shepherd.Step.StepOptions[] = [
   {
     id: "homepage-01",
     text: step01,
@@ -433,101 +433,79 @@ const steps: TourData["steps"] = [
   },
 ];
 
-const eventHandlers: TourData["eventHandlers"] = [
-  {
-    stepId: "homepage-04",
-    eventHandlers: [
-      {
-        event: "show",
-        handler() {
-          const topic = ".topic-listing > li:first-child";
-          const counters = [
-            ".topic-title",
-            ".topic-metadata",
-            ".topic-info-comments",
-            ".topic-info-source",
-            "time",
-            ".topic-voting",
-            ".topic-actions",
-          ];
+export const eventHandlers: TourStepEventHandler[] = [
+  [
+    "homepage-04",
+    [
+      "show",
+      () => {
+        const topic = ".topic-listing > li:first-child";
+        const counters = [
+          ".topic-title",
+          ".topic-metadata",
+          ".topic-info-comments",
+          ".topic-info-source",
+          "time",
+          ".topic-voting",
+          ".topic-actions",
+        ];
 
-          for (const [count, selector] of counters.entries()) {
-            addDatasetCounter(`${topic} ${selector}`, count + 1);
-          }
-        },
+        for (const [count, selector] of counters.entries()) {
+          addDatasetCounter(`${topic} ${selector}`, count + 1);
+        }
       },
     ],
-  },
-  {
-    stepId: "homepage-05",
-    eventHandlers: [
-      {
-        event: "destroy",
-        handler() {
-          removeAllDatasetCounters();
-        },
-      },
-      {
-        event: "show",
-        handler() {
-          encapsulateElements(
-            "homepage-06",
-            "#sidebar .sidebar-controls",
-            "afterend",
-            ["#sidebar .form-search", "#sidebar h2", "#sidebar p"],
-          );
-        },
+  ],
+  [
+    "homepage-05",
+    [
+      "destroy",
+      () => {
+        removeAllDatasetCounters();
       },
     ],
-  },
-  {
-    stepId: "homepage-06",
-    eventHandlers: [
-      {
-        event: "show",
-        handler() {
-          encapsulateElements(
-            "homepage-07",
-            "#sidebar .divider",
-            "beforebegin",
-            ["#sidebar .nav", '#sidebar [href="/groups"'],
-          );
-        },
+  ],
+  [
+    "homepage-05",
+    [
+      "show",
+      () => {
+        encapsulateElements(
+          "homepage-06",
+          "#sidebar .sidebar-controls",
+          "afterend",
+          ["#sidebar .form-search", "#sidebar h2", "#sidebar p"],
+        );
       },
     ],
-  },
-  {
-    stepId: "homepage-08",
-    eventHandlers: [
-      {
-        event: "show",
-        handler() {
-          const filteredTags =
-            document.querySelector<HTMLDetailsElement>("#sidebar details") ??
-            undefined;
-          if (filteredTags === undefined) {
-            console.warn("Element is unexpectedly undefined");
-            return;
-          }
+  ],
+  [
+    "homepage-06",
+    [
+      "show",
+      () => {
+        encapsulateElements("homepage-07", "#sidebar .divider", "beforebegin", [
+          "#sidebar .nav",
+          '#sidebar [href="/groups"',
+        ]);
+      },
+    ],
+  ],
+  [
+    "homepage-08",
+    [
+      "show",
+      () => {
+        const filteredTags =
+          document.querySelector<HTMLDetailsElement>("#sidebar details") ??
+          undefined;
+        if (filteredTags === undefined) {
+          console.warn("Element is unexpectedly undefined");
+          return;
+        }
 
-          filteredTags.open = true;
-        },
+        filteredTags.open = true;
       },
     ],
-  },
+  ],
 ];
-
-const requirements: TourData["requirements"] = {
-  mustBeLoggedIn: false,
-  path: "/",
-};
-
-export const homepageTour: TourData = {
-  id: TourId.InterfaceHomepage,
-  title: "The Tildes Homepage",
-  description: "Let's take a look at the home page and all we can do there.",
-  displayInOptionsPage: true,
-  eventHandlers,
-  requirements,
-  steps,
-};

source/tours/introduction.tsx

@@ -1,5 +1,5 @@
-import {fromStorage, StorageKey} from "../storage/common.js";
-import {TourId, type TourData} from "./types.js";
+import type Shepherd from "shepherd.js";
+import {createIntroductionUnderstood} from "../storage/common.js";
 import {openOptionsPageFromBackground, renderInContainer} from "./utilities.js";
 
 const step01 = renderInContainer(
@@ -82,7 +82,7 @@ const step03 = renderInContainer(
   </>,
 );
 
-const steps: TourData["steps"] = [
+export const introductionSteps: Shepherd.Step.StepOptions[] = [
   {
     canClickTarget: false,
     id: "introduction-01",
@@ -103,9 +103,7 @@ const steps: TourData["steps"] = [
         classes: "btn",
         text: "I understand",
         async action() {
-          const introductionUnderstood = await fromStorage(
-            StorageKey.IntroductionUnderstood,
-          );
+          const introductionUnderstood = await createIntroductionUnderstood();
           introductionUnderstood.value = true;
           await introductionUnderstood.save();
           this.complete();
@@ -124,21 +122,3 @@ const steps: TourData["steps"] = [
     text: step03,
   },
 ];
-
-const eventHandlers: TourData["eventHandlers"] = [];
-
-const requirements: TourData["requirements"] = {
-  mustBeLoggedIn: false,
-  path: "/",
-};
-
-export const introductionTour: TourData = {
-  id: TourId.Introduction,
-  title: "Tildes Shepherd Introduction",
-  description:
-    "A short introduction to Tildes Shepherd and how the tours work.",
-  displayInOptionsPage: true,
-  eventHandlers,
-  requirements,
-  steps,
-};

source/tours/shared/exports.ts

@@ -1,2 +1 @@
 export * from "./logged-out-warning.js";
-export * from "./tour-error.js";

source/tours/shared/logged-out-warning.tsx

@@ -1,6 +1,5 @@
 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;

source/tours/shared/tour-error.tsx

@@ -1,29 +0,0 @@
-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: {
-      buttons: [
-        {
-          classes: "btn",
-          text: "Continue",
-          action() {
-            this.complete();
-          },
-        },
-      ],
-    },
-    useModalOverlay: true,
-  });
-
-  tour.addStep({
-    text: renderInContainer(<p class="tish-warning">{text}</p>),
-  });
-
-  tour.start();
-}

source/tours/types.ts

@@ -1,58 +0,0 @@
-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<Shepherd.Step["on"]>[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;
-};

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 the element to apply the counter to, if the
+ * @param selector The selector of 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.
  */

source/types.d.ts

@@ -1,7 +1,12 @@
-export {};
+import type Shepherd from "shepherd.js";
 
 declare global {
   const $browser: "chromium" | "firefox";
   const $dev: boolean;
   const $test: boolean;
+
+  type TourStepEvent = "show" | "destroy";
+  type TourStepEventFunction = Parameters<Shepherd.Step["on"]>[1];
+  type TourStepEventHandler = [string, [TourStepEvent, TourStepEventFunction]];
+  type TourStepOptions = Shepherd.Step.StepOptions;
 }