docs(MultiPageDialog): add user documentation

src/common/gui/dialogs/MultiPageDialog.ts

@@ -26,6 +26,66 @@ type Pages<PageKey extends string> = {
 }
 type GetPagesFunc<PageKey extends string> = (dialog: Dialog, navigateToPage: (targetPage: PageKey) => void, goBack: (to?: PageKey) => void) => Pages<PageKey>
 
+/**
+ * Allows to build a dialog with pagination, navigation & transitioning effect.
+ *
+ * @example
+ * type Page = "event" | "guests"
+ *
+ * new MultiPageDialog<Page>("event", (
+ * 	dialog, // : Dialog,
+ * 	navigateToPage, // : (targetPage: "event" | "guests") => void,
+ * 	goBack, // : (targetPage?: "event" | "guests") => void,
+ * ) => ({
+ * 	event: {
+ * 		// The content of the events page shown within the dialog.
+ * 		// It could also be a separate class implementing `Component` interface representing the content.
+ * 		content: [
+ * 			m("h1", "Jogging, 14:00-14:30"),
+ * 			m("button", {
+ * 				// When clicking the button, doing a forwards transition to the page `guests`
+ * 				onclick: () => navigateToPage("guests"),
+ * 			}, "Manage guests"),
+ * 		],
+ * 		// The title of the 'events' page, shown in the dialog's header bar
+ * 		title: "Jogging",
+ * 		// A button, displayed in the dialog's header bar for the respective page.
+ * 		leftAction: { label: "close_alt", title: "close_alt", type: ButtonType.Secondary, click: () => dialog.onClose() },
+ * 	},
+ * 	guests: {
+ * 		content: m("", [
+ * 			m("h1", "Guests"),
+ * 			m("h3", "John Doe"),
+ * 			m("h3", "Jane Doe"),
+ * 		]),
+ * 		leftAction: {
+ * 			label: "back_action",
+ * 			title: "back_action",
+ * 			type: ButtonType.Secondary,
+ * 			// When clicked, perform a backwards animation to the `event` page.
+ * 			click: () => goBack("event"),
+ * 		},
+ * 		rightAction: {
+ * 			label: "save_action", title: "save_action", type: ButtonType.Primary, click: () => {
+ * 				// ... do something and close the dialog afterward.
+ *
+ * 				dialog.onClose()
+ * 			},
+ * 		},
+ * 		title: "Guests for jogging event",
+ * 		onClose: () => {
+ * 			// ... do something before the dialog is closed and close it afterward with `dialog.close()`
+ *
+ * 			dialog.close()
+ * 		},
+ * 	},
+ * }), 600)
+ * 	.getDialog()
+ * 	.show()
+ *
+ * @template PageKey - A union type representing the pages the dialog is using. Must be string.
+ * @class
+ */
 export class MultiPageDialog<PageKey extends string> {
 	private readonly currentPageStream: stream<PageKey>
 	private readonly pageStackStream: stream<PageKey[]>
@@ -38,7 +98,17 @@ export class MultiPageDialog<PageKey extends string> {
 		middle: "emptyString_msg",
 	}
 
-	constructor(defaultPage: PageKey, height: number, private readonly getPages: GetPagesFunc<PageKey>) {
+	/**
+	 * Builds a new `MultiPageDialog` instance.
+	 *
+	 * See {@link MultiPageDialog} documentation for usage guide.
+	 *
+	 * @constructor
+	 * @param defaultPage - The first page displayed after opening the dialog.
+	 * @param getPages - The function to return the configured pages.
+	 * @param height - The height of the dialog in pixels.
+	 **/
+	constructor(defaultPage: PageKey, private readonly getPages: GetPagesFunc<PageKey>, height: number = 666) {
 		this.currentPageStream = stream(defaultPage)
 		this.pageStackStream = stream([defaultPage])
 

src/common/ratings/InAppRatingDialog.ts

@@ -16,17 +16,16 @@ import { DateTime } from "luxon"
 import { ButtonType } from "../gui/base/Button.js"
 import { AndroidPlayStorePage } from "./pages/AndroidPlayStorePage.js"
 
-export enum RatingPages {
-	HOW_ARE_WE_DOING,
-	ANDROID_PLAY_STORE,
-}
-
 export function showAppRatingDialog(triggerType: TriggerType): void {
 	completeTriggerStage(triggerType)
 
-	const dialog = new MultiPageDialog<"howAreWeDoing" | "androidPlayStore">("howAreWeDoing", 666, (dialog, navigateToPage, goBack) => ({
+	const dialog = new MultiPageDialog<"howAreWeDoing" | "androidPlayStore">("howAreWeDoing", (dialog, navigateToPage, _) => ({
 		howAreWeDoing: {
-			content: m(HowAreWeDoingPage, { triggerType, dialog, goToAndroidPlayStorePage: () => navigateToPage("androidPlayStore") }),
+			content: m(HowAreWeDoingPage, {
+				triggerType,
+				dialog,
+				goToAndroidPlayStorePage: () => navigateToPage("androidPlayStore"),
+			}),
 			rightAction: {
 				label: "notNow_label",
 				click: () => {

src/common/support/SupportDialog.ts

@@ -45,7 +45,7 @@ export async function showSupportDialog(logins: LoginController) {
 
 	const dialog = new MultiPageDialog<
 		"home" | "categoryDetail" | "topicDetail" | "contactSupport" | "solutionWasHelpful" | "supportRequestSent" | "emailSupportBehindPaywall"
-	>("home", 666, (dialog, navigateToPage, goBack) => ({
+	>("home", (dialog, navigateToPage, goBack) => ({
 		home: {
 			title: lang.get("supportMenu_label"),
 			content: m(SupportLandingPage, {
@@ -188,16 +188,6 @@ function filterCategories(supportData: SupportData) {
 	return categories.filter((cat) => cat.topics.length > 0)
 }
 
-enum SupportPages {
-	CATEGORIES,
-	CATEGORY_DETAIL,
-	TOPIC_DETAIL,
-	CONTACT_SUPPORT,
-	SUPPORT_REQUEST_SENT,
-	EMAIL_SUPPORT_BEHIND_PAYWALL,
-	SOLUTION_WAS_HELPFUL,
-}
-
 function isEnabled(visibility: number, mask: SupportVisibilityMask) {
 	return !!(visibility & mask)
 }