Improved the documentation of modules
authorAlexander Ebert <ebert@woltlab.com>
Wed, 5 Jan 2022 17:58:31 +0000 (18:58 +0100)
committerAlexander Ebert <ebert@woltlab.com>
Wed, 5 Jan 2022 17:58:31 +0000 (18:58 +0100)
18 files changed:
ts/WoltLabSuite/Core/Acp/Ui/Page/Menu/Main/Backend.ts
ts/WoltLabSuite/Core/Bootstrap.ts
ts/WoltLabSuite/Core/Ui/Page/Menu/Container.ts
ts/WoltLabSuite/Core/Ui/Page/Menu/Main.ts
ts/WoltLabSuite/Core/Ui/Page/Menu/Main/Frontend.ts
ts/WoltLabSuite/Core/Ui/Page/Menu/Main/Provider.ts
ts/WoltLabSuite/Core/Ui/Page/Menu/Provider.ts
ts/WoltLabSuite/Core/Ui/Page/Menu/User.ts
ts/WoltLabSuite/Core/Ui/Search.ts
ts/WoltLabSuite/Core/Ui/User/Menu/Manager.ts
wcfsetup/install/files/js/WoltLabSuite/Core/Acp/Ui/Page/Menu/Main/Backend.js
wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Container.js
wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Main.js
wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Main/Frontend.js
wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Main/Provider.js
wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/Provider.js
wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Page/Menu/User.js
wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Search.js

index 53273bdc94270befff67c7373164ed12aeafe65d..adb980799b6aee6663fee47d9e1fe3c41a2e0efc 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
+ * @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[] {
index 5d5c7d7b486869c4b3afcabe20ec62e7d3a9d6a0..2a15a9b9c9df18adb12edd15f9630e22eababdc4 100644 (file)
@@ -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) {
index 9fd9c126a0948a7b3a01aa63f34df31448df78b4..d8b5463d1dd78ca75ed5c0871a1bee00aee750a2 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
+ * @module WoltLabSuite/Core/Ui/Page/Menu/Container
+ */
+
 import { PageMenuProvider } from "./Provider";
 import { createFocusTrap, FocusTrap } from "focus-trap";
 import { pageOverlayClose, pageOverlayOpen, scrollDisable, scrollEnable } from "../../Screen";
index ee0e1204e12c8514a0d51ceeff4f0c33b830ab6a..793b8015b4b6126e85b8d3d1d4a7b64be1330428 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
  * @module WoltLabSuite/Core/Ui/Page/Menu/Main
  */
index 1a7c07ab22e05876f59451dae334cc37d888bb03..0cabfc86b7997ef2a1769b30b2305c8aeddea6f1 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
+ * @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");
index f765dda658cf1d0f1d2d7db424fc1d85dc9f6b74..9bb39333e9a823f546b407009eec802061772c9c 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
+ * @module WoltLabSuite/Core/Ui/Page/Menu/Provider
+ * @woltlabExcludeBundle all
+ */
+
 export type MenuItemDepth = 0 | 1 | 2;
 
 export type MenuItem = {
index 5f2bb0ea0c3c62d98b475e480dfd06e792b717b6..2d6ccc0d893afeadbd351d441bbbaded8726f662 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
+ * @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;
 }
index 738f4cc9dca70ff259b43233522635838d5f2ccb..d540984ccb1daef0fe6ff5117732e72fc43ed7f9 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
  * @module WoltLabSuite/Core/Ui/Page/Menu/User
+ * @woltlabExcludeBundle tiny
  */
 
 import PageMenuContainer, { Orientation } from "./Container";
index 7a1b905cdb8eab608da337d7f4bb3f7e238e7f5c..1c675b17a3b9026b46c374c0a4ffbe214d535275 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
- * @module  WoltLabSuite/Core/Ui/Page/Header/Fixed
+ * @author Alexander Ebert
+ * @copyright 2001-2022 WoltLab GmbH
+ * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @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();
index 5864b7154f281dbb768d5c0d7ad7d95d9a0f6d77..5161e296791fdba41e4898d75fa0ee7da2236341 100644 (file)
@@ -94,7 +94,7 @@ function getView(provider: UserMenuProvider): UserMenuView {
   return views.get(provider)!;
 }
 
-export function getUserMenuProviders(): Set<UserMenuProvider> {
+export function getUserMenuProviders(): ReadonlySet<UserMenuProvider> {
   return providers;
 }
 
index dde7a50681f69758849b7d8fcd2104e70e7f6974..7268fcc63113d8280a8907e632453f61629191b1 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
+ * @module WoltLabSuite/Core/Acp/Ui/Page/Menu/Main/Backend
+ */
 define(["require", "exports"], function (require, exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
index 0df21e89a875487c4b47a858cbc60bfe63702661..145586f94da5a8cc0037a47613115cfa09beed34 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
+ * @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 });
index d0a16cd747a3758567013f5050afa173f16d419d..4d861199a41ab34cdf3a9452c1a361a20e9ebca3 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
  * @module WoltLabSuite/Core/Ui/Page/Menu/Main
  */
index 99dbd90989254716015ddd906c045536c5d820c0..034d9315ad7f82ac4b02fa41f55b9d4f3fa9ec39 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
+ * @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 = [];
index 2ae92b6a8b5db3c75f02775e473eca4300b025f8..4543d5125d7a2bb2e955dc219914b53ba251f8de 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
+ * @module WoltLabSuite/Core/Ui/Page/Menu/Provider
+ * @woltlabExcludeBundle all
+ */
 define(["require", "exports"], function (require, exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
index 2ae92b6a8b5db3c75f02775e473eca4300b025f8..86333d31be0f1dfcee38bae3ab7bf9b636e85a4c 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
+ * @module WoltLabSuite/Core/Ui/Page/Menu/Provider
+ * @woltlabExcludeBundle all
+ */
 define(["require", "exports"], function (require, exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
index cbe37f1ffbd5fded9e31d82d5657368ed9084491..11324603d7a1f0ea7b3fcb94325c39364ea5bda9 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
  * @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";
index 5bd94e507856a3a1f1c2f0742758c141716319b5..7d9fa04ee036206c19d6384bca5aa54cb548fc74 100644 (file)
@@ -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 <http://opensource.org/licenses/lgpl-license.php>
- * @module  WoltLabSuite/Core/Ui/Page/Header/Fixed
+ * @author Alexander Ebert
+ * @copyright 2001-2022 WoltLab GmbH
+ * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @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();