From: Alexander Ebert Date: Wed, 5 Jan 2022 17:58:31 +0000 (+0100) Subject: Improved the documentation of modules X-Git-Tag: 5.5.0_Alpha_1~242^2~1 X-Git-Url: https://git.stricted.de/?a=commitdiff_plain;h=e18d07b93345cdeb04bff8eb6821a76d36db4109;p=GitHub%2FWoltLab%2FWCF.git Improved the documentation of modules --- diff --git a/ts/WoltLabSuite/Core/Acp/Ui/Page/Menu/Main/Backend.ts b/ts/WoltLabSuite/Core/Acp/Ui/Page/Menu/Main/Backend.ts index 53273bdc94..adb980799b 100644 --- a/ts/WoltLabSuite/Core/Acp/Ui/Page/Menu/Main/Backend.ts +++ b/ts/WoltLabSuite/Core/Acp/Ui/Page/Menu/Main/Backend.ts @@ -1,3 +1,12 @@ +/** + * Provides the menu items for the mobile main menu in the admin panel. + * + * @author Alexander Ebert + * @copyright 2001-2022 WoltLab GmbH + * @license GNU Lesser General Public License + * @module WoltLabSuite/Core/Acp/Ui/Page/Menu/Main/Backend + */ + import { MenuItem, PageMenuMainProvider } from "../../../../../Ui/Page/Menu/Main/Provider"; function getSubMenuItems(subMenu: HTMLElement, menuItem: string): MenuItem[] { diff --git a/ts/WoltLabSuite/Core/Bootstrap.ts b/ts/WoltLabSuite/Core/Bootstrap.ts index 5d5c7d7b48..2a15a9b9c9 100644 --- a/ts/WoltLabSuite/Core/Bootstrap.ts +++ b/ts/WoltLabSuite/Core/Bootstrap.ts @@ -31,10 +31,10 @@ import * as UiObjectAction from "./Ui/Object/Action"; import * as UiObjectActionDelete from "./Ui/Object/Action/Delete"; import * as UiObjectActionToggle from "./Ui/Object/Action/Toggle"; import { init as initSearch } from "./Ui/Search"; +import { PageMenuMainProvider } from "./Ui/Page/Menu/Main/Provider"; // perfectScrollbar does not need to be bound anywhere, it just has to be loaded for WCF.js import "perfect-scrollbar"; -import { PageMenuMainProvider } from "./Ui/Page/Menu/Main/Provider"; // non strict equals by intent if (window.WCF == null) { diff --git a/ts/WoltLabSuite/Core/Ui/Page/Menu/Container.ts b/ts/WoltLabSuite/Core/Ui/Page/Menu/Container.ts index 9fd9c126a0..d8b5463d1d 100644 --- a/ts/WoltLabSuite/Core/Ui/Page/Menu/Container.ts +++ b/ts/WoltLabSuite/Core/Ui/Page/Menu/Container.ts @@ -1,3 +1,13 @@ +/** + * Wrapper logic for elements that are placed over the main content + * such as the mobile main menu and the user menu with its tabs. + * + * @author Alexander Ebert + * @copyright 2001-2022 WoltLab GmbH + * @license GNU Lesser General Public License + * @module WoltLabSuite/Core/Ui/Page/Menu/Container + */ + import { PageMenuProvider } from "./Provider"; import { createFocusTrap, FocusTrap } from "focus-trap"; import { pageOverlayClose, pageOverlayOpen, scrollDisable, scrollEnable } from "../../Screen"; diff --git a/ts/WoltLabSuite/Core/Ui/Page/Menu/Main.ts b/ts/WoltLabSuite/Core/Ui/Page/Menu/Main.ts index ee0e1204e1..793b8015b4 100644 --- a/ts/WoltLabSuite/Core/Ui/Page/Menu/Main.ts +++ b/ts/WoltLabSuite/Core/Ui/Page/Menu/Main.ts @@ -2,7 +2,7 @@ * Provides the touch-friendly main menu. * * @author Alexander Ebert - * @copyright 2001-2021 WoltLab GmbH + * @copyright 2001-2022 WoltLab GmbH * @license GNU Lesser General Public License * @module WoltLabSuite/Core/Ui/Page/Menu/Main */ diff --git a/ts/WoltLabSuite/Core/Ui/Page/Menu/Main/Frontend.ts b/ts/WoltLabSuite/Core/Ui/Page/Menu/Main/Frontend.ts index 1a7c07ab22..0cabfc86b7 100644 --- a/ts/WoltLabSuite/Core/Ui/Page/Menu/Main/Frontend.ts +++ b/ts/WoltLabSuite/Core/Ui/Page/Menu/Main/Frontend.ts @@ -1,3 +1,12 @@ +/** + * Provides the menu items for the mobile main menu in the frontend. + * + * @author Alexander Ebert + * @copyright 2001-2022 WoltLab GmbH + * @license GNU Lesser General Public License + * @module WoltLabSuite/Core/Ui/Page/Menu/Main/Frontend + */ + import { MenuItem, MenuItemDepth, PageMenuMainProvider } from "./Provider"; function normalizeMenuItem(menuItem: HTMLElement, depth: MenuItemDepth): MenuItem { @@ -7,7 +16,7 @@ function normalizeMenuItem(menuItem: HTMLElement, depth: MenuItemDepth): MenuIte let counter = 0; const outstandingItems = anchor.querySelector(".boxMenuLinkOutstandingItems"); if (outstandingItems) { - counter = +outstandingItems.textContent!.replace(/[^0-9]/, ""); + counter = parseInt(outstandingItems.textContent!.replace(/[^0-9]/, ""), 10); } const subMenu = menuItem.querySelector("ol"); diff --git a/ts/WoltLabSuite/Core/Ui/Page/Menu/Main/Provider.ts b/ts/WoltLabSuite/Core/Ui/Page/Menu/Main/Provider.ts index f765dda658..9bb39333e9 100644 --- a/ts/WoltLabSuite/Core/Ui/Page/Menu/Main/Provider.ts +++ b/ts/WoltLabSuite/Core/Ui/Page/Menu/Main/Provider.ts @@ -1,3 +1,14 @@ +/** + * Common interface and data types for containers that + * span the entire content area. + * + * @author Alexander Ebert + * @copyright 2001-2022 WoltLab GmbH + * @license GNU Lesser General Public License + * @module WoltLabSuite/Core/Ui/Page/Menu/Provider + * @woltlabExcludeBundle all + */ + export type MenuItemDepth = 0 | 1 | 2; export type MenuItem = { diff --git a/ts/WoltLabSuite/Core/Ui/Page/Menu/Provider.ts b/ts/WoltLabSuite/Core/Ui/Page/Menu/Provider.ts index 5f2bb0ea0c..2d6ccc0d89 100644 --- a/ts/WoltLabSuite/Core/Ui/Page/Menu/Provider.ts +++ b/ts/WoltLabSuite/Core/Ui/Page/Menu/Provider.ts @@ -1,13 +1,46 @@ +/** + * Page menus are placed above the content and their visibility + * is controlled through buttons placed in the page header. + * + * @author Alexander Ebert + * @copyright 2001-2022 WoltLab GmbH + * @license GNU Lesser General Public License + * @module WoltLabSuite/Core/Ui/Page/Menu/Provider + * @woltlabExcludeBundle all + */ + export interface PageMenuProvider { + /** + * Disables this menu when switching from the mobile to the desktop view. + */ disable(): void; + /** + * Enables the menu once the mobile view became active. + */ enable(): void; + /** + * Returns arbitrary HTML elements that are placed inside the overlay container. + */ getContent(): DocumentFragment; + /** + * Provides the button that is used to change the visibility of the overlay container. + */ getMenuButton(): HTMLElement; + /** + * Suspends the activity of the container and returns any borrowed HTML elements + * to their previous position. It is primarily used to restore the UI in case the + * mobile view bcomes inactive. + */ sleep(): void; + /** + * Restores the view by moving any borrowed HTML elements back into the container. + * This method is also responsible to refresh the UI in case the underlying data + * has changed. + */ wakeup(): void; } diff --git a/ts/WoltLabSuite/Core/Ui/Page/Menu/User.ts b/ts/WoltLabSuite/Core/Ui/Page/Menu/User.ts index 738f4cc9dc..d540984ccb 100644 --- a/ts/WoltLabSuite/Core/Ui/Page/Menu/User.ts +++ b/ts/WoltLabSuite/Core/Ui/Page/Menu/User.ts @@ -2,9 +2,10 @@ * Provides the touch-friendly user menu. * * @author Alexander Ebert - * @copyright 2001-2021 WoltLab GmbH + * @copyright 2001-2022 WoltLab GmbH * @license GNU Lesser General Public License * @module WoltLabSuite/Core/Ui/Page/Menu/User + * @woltlabExcludeBundle tiny */ import PageMenuContainer, { Orientation } from "./Container"; diff --git a/ts/WoltLabSuite/Core/Ui/Search.ts b/ts/WoltLabSuite/Core/Ui/Search.ts index 7a1b905cdb..1c675b17a3 100644 --- a/ts/WoltLabSuite/Core/Ui/Search.ts +++ b/ts/WoltLabSuite/Core/Ui/Search.ts @@ -1,10 +1,12 @@ /** - * Manages the sticky page header. + * Controls the behavior and placement of the search input depending on + * the context (frontend or admin panel) and the active view (mobile or + * desktop). * - * @author Alexander Ebert - * @copyright 2001-2019 WoltLab GmbH - * @license GNU Lesser General Public License - * @module WoltLabSuite/Core/Ui/Page/Header/Fixed + * @author Alexander Ebert + * @copyright 2001-2022 WoltLab GmbH + * @license GNU Lesser General Public License + * @module WoltLabSuite/Core/Ui/Search */ import * as EventHandler from "../Event/Handler"; @@ -81,6 +83,9 @@ function initMobileSearch(): void { searchButton.setAttribute("aria-expanded", "false"); } else { + // iOS Safari behaves unpredictable when the keyboard focus + // is moved into a HTML element that is inside a parent with + // fixed positioning *and* the page had been scrolled down. if (Environment.platform() === "ios") { _scrollTop = document.body.scrollTop; UiScreen.scrollDisable(); diff --git a/ts/WoltLabSuite/Core/Ui/User/Menu/Manager.ts b/ts/WoltLabSuite/Core/Ui/User/Menu/Manager.ts index 5864b7154f..5161e29679 100644 --- a/ts/WoltLabSuite/Core/Ui/User/Menu/Manager.ts +++ b/ts/WoltLabSuite/Core/Ui/User/Menu/Manager.ts @@ -94,7 +94,7 @@ function getView(provider: UserMenuProvider): UserMenuView { return views.get(provider)!; } -export function getUserMenuProviders(): Set { +export function getUserMenuProviders(): ReadonlySet { return providers; } diff --git a/wcfsetup/install/files/js/WoltLabSuite/Core/Acp/Ui/Page/Menu/Main/Backend.js b/wcfsetup/install/files/js/WoltLabSuite/Core/Acp/Ui/Page/Menu/Main/Backend.js index dde7a50681..7268fcc631 100644 --- a/wcfsetup/install/files/js/WoltLabSuite/Core/Acp/Ui/Page/Menu/Main/Backend.js +++ b/wcfsetup/install/files/js/WoltLabSuite/Core/Acp/Ui/Page/Menu/Main/Backend.js @@ -1,3 +1,11 @@ +/** + * Provides the menu items for the mobile main menu in the admin panel. + * + * @author Alexander Ebert + * @copyright 2001-2022 WoltLab GmbH + * @license GNU Lesser General Public License + * @module WoltLabSuite/Core/Acp/Ui/Page/Menu/Main/Backend + */ define(["require", "exports"], function (require, exports) { "use strict"; Object.defineProperty(exports, "__esModule", { value: true }); diff --git a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Container.js b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Container.js index 0df21e89a8..145586f94d 100644 --- a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Container.js +++ b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Container.js @@ -1,3 +1,12 @@ +/** + * Wrapper logic for elements that are placed over the main content + * such as the mobile main menu and the user menu with its tabs. + * + * @author Alexander Ebert + * @copyright 2001-2022 WoltLab GmbH + * @license GNU Lesser General Public License + * @module WoltLabSuite/Core/Ui/Page/Menu/Container + */ define(["require", "exports", "tslib", "focus-trap", "../../Screen", "../../CloseOverlay", "../../../Dom/Util"], function (require, exports, tslib_1, focus_trap_1, Screen_1, CloseOverlay_1, Util_1) { "use strict"; Object.defineProperty(exports, "__esModule", { value: true }); diff --git a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Main.js b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Main.js index d0a16cd747..4d861199a4 100644 --- a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Main.js +++ b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Main.js @@ -2,7 +2,7 @@ * Provides the touch-friendly main menu. * * @author Alexander Ebert - * @copyright 2001-2021 WoltLab GmbH + * @copyright 2001-2022 WoltLab GmbH * @license GNU Lesser General Public License * @module WoltLabSuite/Core/Ui/Page/Menu/Main */ diff --git a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Main/Frontend.js b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Main/Frontend.js index 99dbd90989..034d9315ad 100644 --- a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Main/Frontend.js +++ b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Main/Frontend.js @@ -1,3 +1,11 @@ +/** + * Provides the menu items for the mobile main menu in the frontend. + * + * @author Alexander Ebert + * @copyright 2001-2022 WoltLab GmbH + * @license GNU Lesser General Public License + * @module WoltLabSuite/Core/Ui/Page/Menu/Main/Frontend + */ define(["require", "exports"], function (require, exports) { "use strict"; Object.defineProperty(exports, "__esModule", { value: true }); @@ -8,7 +16,7 @@ define(["require", "exports"], function (require, exports) { let counter = 0; const outstandingItems = anchor.querySelector(".boxMenuLinkOutstandingItems"); if (outstandingItems) { - counter = +outstandingItems.textContent.replace(/[^0-9]/, ""); + counter = parseInt(outstandingItems.textContent.replace(/[^0-9]/, ""), 10); } const subMenu = menuItem.querySelector("ol"); let children = []; diff --git a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Main/Provider.js b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Main/Provider.js index 2ae92b6a8b..4543d5125d 100644 --- a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Main/Provider.js +++ b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Main/Provider.js @@ -1,3 +1,13 @@ +/** + * Common interface and data types for containers that + * span the entire content area. + * + * @author Alexander Ebert + * @copyright 2001-2022 WoltLab GmbH + * @license GNU Lesser General Public License + * @module WoltLabSuite/Core/Ui/Page/Menu/Provider + * @woltlabExcludeBundle all + */ define(["require", "exports"], function (require, exports) { "use strict"; Object.defineProperty(exports, "__esModule", { value: true }); diff --git a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Provider.js b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Provider.js index 2ae92b6a8b..86333d31be 100644 --- a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Provider.js +++ b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Provider.js @@ -1,3 +1,13 @@ +/** + * Page menus are placed above the content and their visibility + * is controlled through buttons placed in the page header. + * + * @author Alexander Ebert + * @copyright 2001-2022 WoltLab GmbH + * @license GNU Lesser General Public License + * @module WoltLabSuite/Core/Ui/Page/Menu/Provider + * @woltlabExcludeBundle all + */ define(["require", "exports"], function (require, exports) { "use strict"; Object.defineProperty(exports, "__esModule", { value: true }); diff --git a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/User.js b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/User.js index cbe37f1ffb..11324603d7 100644 --- a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/User.js +++ b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/User.js @@ -2,9 +2,10 @@ * Provides the touch-friendly user menu. * * @author Alexander Ebert - * @copyright 2001-2021 WoltLab GmbH + * @copyright 2001-2022 WoltLab GmbH * @license GNU Lesser General Public License * @module WoltLabSuite/Core/Ui/Page/Menu/User + * @woltlabExcludeBundle tiny */ define(["require", "exports", "tslib", "./Container", "../../../Language", "../../User/Menu/Manager", "../../../Dom/Util", "../../User/Menu/ControlPanel", "../../../Event/Handler"], function (require, exports, tslib_1, Container_1, Language, Manager_1, Util_1, ControlPanel_1, EventHandler) { "use strict"; diff --git a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Search.js b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Search.js index 5bd94e5078..7d9fa04ee0 100644 --- a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Search.js +++ b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Search.js @@ -1,10 +1,12 @@ /** - * Manages the sticky page header. + * Controls the behavior and placement of the search input depending on + * the context (frontend or admin panel) and the active view (mobile or + * desktop). * - * @author Alexander Ebert - * @copyright 2001-2019 WoltLab GmbH - * @license GNU Lesser General Public License - * @module WoltLabSuite/Core/Ui/Page/Header/Fixed + * @author Alexander Ebert + * @copyright 2001-2022 WoltLab GmbH + * @license GNU Lesser General Public License + * @module WoltLabSuite/Core/Ui/Search */ define(["require", "exports", "tslib", "../Event/Handler", "./Alignment", "./CloseOverlay", "./Dropdown/Simple", "./Screen", "../Environment", "../Dom/Util"], function (require, exports, tslib_1, EventHandler, UiAlignment, CloseOverlay_1, Simple_1, UiScreen, Environment, Util_1) { "use strict"; @@ -71,6 +73,9 @@ define(["require", "exports", "tslib", "../Event/Handler", "./Alignment", "./Clo searchButton.setAttribute("aria-expanded", "false"); } else { + // iOS Safari behaves unpredictable when the keyboard focus + // is moved into a HTML element that is inside a parent with + // fixed positioning *and* the page had been scrolled down. if (Environment.platform() === "ios") { _scrollTop = document.body.scrollTop; UiScreen.scrollDisable();