@cedx/base 0.7.0 → 0.9.0

package/package.json

@@ -7,13 +7,13 @@
 	"name": "@cedx/base",
 	"repository": "cedx/base",
 	"type": "module",
-	"version": "0.7.0",
+	"version": "0.9.0",
 	"devDependencies": {
 		"@playwright/browser-chromium": "^1.54.2",
 		"@types/bootstrap": "^5.2.10",
 		"@types/chai": "^5.2.2",
 		"@types/mocha": "^10.0.10",
-		"@types/node": "^24.2.1",
+		"@types/node": "^24.3.0",
 		"@types/serve-handler": "^6.1.4",
 		"chai": "^5.2.1",
 		"esbuild": "^0.25.9",
@@ -38,9 +38,6 @@
 		"lib/",
 		"src/Client/"
 	],
-	"imports": {
-		"#Base/*.js": "./lib/*.js"
-	},
 	"keywords": [
 		"belin",
 		"core",

package/src/Client/FileExtensions.ts

@@ -1,4 +1,4 @@
-import {Duration} from "#Base/Duration.js";
+import {Duration} from "./Duration.js";
 
 /**
  * Downloads the specified file.

package/src/Client/Hosting/Environment.ts

@@ -0,0 +1,25 @@
+/**
+ * Commonly used environment names.
+ */
+export const Environment = Object.freeze({
+
+	/**
+	 * Specifies the development environment.
+	 */
+	Development: "Development",
+
+	/**
+	 * Specifies the production environment.
+	 */
+	Production: "Production",
+
+	/**
+	 * Specifies the staging environment.
+	 */
+	Staging: "Staging"
+});
+
+/**
+ * Commonly used environment names.
+ */
+export type Environment = typeof Environment[keyof typeof Environment];

package/src/Client/Hosting/HostEnvironment.ts

@@ -0,0 +1,86 @@
+import {Environment} from "./Environment.js";
+
+/**
+ * Provides information about the hosting environment an application is running in.
+ */
+export class HostEnvironment {
+
+	/**
+	 * The name of the application.
+	 */
+	readonly applicationName: string;
+
+	/**
+	 * The path to the directory that contains the application content files.
+	 */
+	readonly contentRootPath: string;
+
+	/**
+	 * The name of the environment.
+	 */
+	readonly environmentName: string;
+
+	/**
+	 * Creates a new host environment.
+	 * @param options An object providing values to initialize this instance.
+	 */
+	constructor(options: HostEnvironmentOptions = {}) {
+		this.applicationName = options.applicationName ?? document.head.querySelector<HTMLMetaElement>('meta[name="application-name"]')?.content ?? location.hostname;
+		this.contentRootPath = options.contentRootPath ?? document.head.querySelector("base")?.getAttribute("href") ?? "/";
+		this.environmentName = options.environmentName ?? Environment.Production;
+	}
+
+	/**
+	 * Checks if the current environment name is {@link Environment.Development}.
+	 * @returns `true` if the environment name is {@link Environment.Development}, otherwise `false`.
+	 */
+	get isDevelopment(): boolean {
+		return this.isEnvironment(Environment.Development);
+	}
+
+	/**
+	 * Checks if the current environment name is {@link Environment.Production}.
+	 * @returns `true` if the environment name is {@link Environment.Production}, otherwise `false`.
+	 */
+	get isProduction(): boolean {
+		return this.isEnvironment(Environment.Production);
+	}
+
+	/**
+	 * Checks if the current environment name is {@link Environment.Staging}.
+	 * @returns `true` if the environment name is {@link Environment.Staging}, otherwise `false`.
+	 */
+	get isStaging(): boolean {
+		return this.isEnvironment(Environment.Staging);
+	}
+
+	/**
+	 * Compares the current host environment name against the specified value.
+	 * @param environmentName The environment name to validate against.
+	 * @returns `true` if the specified name is the same as the current environment, otherwise `false`.
+	 */
+	isEnvironment(environmentName: string): boolean {
+		return this.environmentName == environmentName;
+	}
+}
+
+/**
+ * Defines the options of a {@link HostEnvironment} instance.
+ */
+export type HostEnvironmentOptions = Partial<{
+
+	/**
+	 * The name of the application.
+	 */
+	applicationName: string;
+
+	/**
+	 * The path to the directory that contains the application content files.
+	 */
+	contentRootPath: string;
+
+	/**
+	 * The name of the environment.
+	 */
+	environmentName: string;
+}>;

package/src/Client/Hosting/tsconfig.json

@@ -0,0 +1,13 @@
+{
+	"extends": "../../../tsconfig.json",
+	"include": ["**/*.ts"],
+	"compilerOptions": {
+		"composite": true,
+		"declaration": true,
+		"declarationMap": true,
+		"noEmit": false,
+		"outDir": "../../../lib/Hosting",
+		"rootDir": ".",
+		"tsBuildInfoFile": "../../../var/Hosting.tsbuildinfo"
+	}
+}

package/src/Client/UI/Components/LoadingIndicator.ts

@@ -15,13 +15,28 @@ export class LoadingIndicator extends HTMLElement {
 		customElements.define("loading-indicator", this);
 	}
 
+	/**
+	 * Hides this component.
+	 */
+	hide(): void {
+		this.hidden = true;
+		document.body.classList.remove("loading");
+	}
+
+	/**
+	 * Shows this component.
+	 */
+	show(): void {
+		this.hidden = false;
+		document.body.classList.add("loading");
+	}
+
 	/**
 	 * Starts the loading indicator.
 	 */
 	start(): void {
 		this.#requestCount++;
-		this.hidden = false;
-		document.body.classList.add("loading");
+		this.show();
 	}
 
 	/**
@@ -32,8 +47,7 @@ export class LoadingIndicator extends HTMLElement {
 		this.#requestCount--;
 		if (options.force || this.#requestCount <= 0) {
 			this.#requestCount = 0;
-			this.hidden = true;
-			document.body.classList.remove("loading");
+			this.hide();
 		}
 	}
 }

package/src/Client/UI/Components/OfflineIndicator.ts

@@ -8,7 +8,7 @@ export class OfflineIndicator extends HTMLElement {
 	 */
 	constructor() {
 		super();
-		this.hidden = navigator.onLine;
+		this.#updateHiddenState();
 	}
 
 	/**
@@ -22,22 +22,35 @@ export class OfflineIndicator extends HTMLElement {
 	 * Method invoked when this component is connected.
 	 */
 	connectedCallback(): void {
-		for (const event of ["online", "offline"]) addEventListener(event, this);
+		for (const event of ["online", "offline"]) addEventListener(event, this.#updateHiddenState);
 	}
 
 	/**
 	 * Method invoked when this component is disconnected.
 	 */
 	disconnectedCallback(): void {
-		for (const event of ["online", "offline"]) removeEventListener(event, this);
+		for (const event of ["online", "offline"]) removeEventListener(event, this.#updateHiddenState);
 	}
 
 	/**
-	 * Handles the events.
+	 * Hides this component.
 	 */
-	handleEvent(): void {
-		this.hidden = navigator.onLine;
+	hide(): void {
+		this.hidden = true;
+	}
+
+	/**
+	 * Shows this component.
+	 */
+	show(): void {
+		this.hidden = false;
 	}
+
+	/**
+	 * Updates the hidden state of this component according to the {@link navigator.onLine} property.
+	 */
+	readonly #updateHiddenState: () => void = () =>
+		this.hidden = navigator.onLine;
 }
 
 /**

package/src/Client/UI/Components/TabActivator.ts

@@ -0,0 +1,87 @@
+import {Tab} from "bootstrap";
+import {StorageArea} from "../StorageArea.js";
+
+/**
+ * A component that activates a tab, based on its index saved in the web storage.
+ */
+export class TabActivator extends HTMLElement {
+
+	/**
+	 * Registers the component.
+	 */
+	static {
+		customElements.define("tab-activator", this);
+	}
+
+	/**
+	 * The one-based index of the active tab.
+	 */
+	get activeTabIndex(): number {
+		const index = Number.parseInt(this.storage.getItem(this.storageKey) ?? "1");
+		return Math.max(1, Math.min(this.tabs.length, Number.isNaN(index) ? 1 : index));
+	}
+	set activeTabIndex(value: number) {
+		this.storage.setItem(this.storageKey, value.toString());
+	}
+
+	/**
+	 * The storage object corresponding to the current {@link storageArea}.
+	 */
+	get storage(): globalThis.Storage {
+		return this.storageArea == StorageArea.Local ? localStorage : sessionStorage;
+	}
+
+	/**
+	 * The storage area to use.
+	 */
+	get storageArea(): StorageArea {
+		const value = this.getAttribute("storagearea") as StorageArea;
+		return Object.values(StorageArea).includes(value) ? value : StorageArea.Session;
+	}
+	set storageArea(value: StorageArea) {
+		this.setAttribute("storagearea", value);
+	}
+
+	/**
+	 * The key of the storage entry providing the active tab index.
+	 */
+	get storageKey(): string {
+		const value = this.getAttribute("storagekey") ?? "";
+		return value.trim() || "ActiveTabIndex";
+	}
+	set storageKey(value: string) {
+		this.setAttribute("storagekey", value);
+	}
+
+	/**
+	 * The tab list.
+	 */
+	get tabs(): NodeListOf<HTMLButtonElement> {
+		return this.querySelectorAll(".nav-tabs button");
+	}
+
+	/**
+	 * Method invoked when this component is connected.
+	 */
+	connectedCallback(): void {
+		const {activeTabIndex, tabs} = this;
+		for (let index = 1; index <= tabs.length; index++) {
+			const tab = tabs.item(index - 1);
+			tab.addEventListener("click", () => this.activeTabIndex = index);
+			if (index == activeTabIndex) Tab.getOrCreateInstance(tab).show();
+		}
+	}
+}
+
+/**
+ * Declaration merging.
+ */
+declare global {
+
+	/**
+	 * The map of HTML tag names.
+	 */
+	interface HTMLElementTagNameMap {
+		"tab-activator": TabActivator;
+	}
+}

package/src/Client/UI/Components/ThemeDropdown.ts

@@ -16,14 +16,6 @@ export class ThemeDropdown extends HTMLElement {
 	 */
 	readonly #mediaQuery = matchMedia("(prefers-color-scheme: dark)");
 
-	/**
-	 * Creates a new theme dropdown.
-	 */
-	constructor() {
-		super();
-		for (const button of this.querySelectorAll("button")) button.addEventListener("click", this.#setTheme.bind(this));
-	}
-
 	/**
 	 * Registers the component.
 	 */
@@ -110,7 +102,9 @@ export class ThemeDropdown extends HTMLElement {
 	 * Method invoked when this component is connected.
 	 */
 	connectedCallback(): void {
-		this.#mediaQuery.addEventListener("change", this);
+		for (const button of this.querySelectorAll("button")) button.addEventListener("click", this.#setTheme);
+		this.#mediaQuery.addEventListener("change", this.#applyTheme);
+
 		const appTheme = localStorage.getItem(this.storageKey) as AppTheme|null;
 		if (appTheme) this.setAttribute("apptheme", appTheme);
 	}
@@ -119,34 +113,28 @@ export class ThemeDropdown extends HTMLElement {
 	 * Method invoked when this component is disconnected.
 	 */
 	disconnectedCallback(): void {
-		this.#mediaQuery.removeEventListener("change", this);
-	}
-
-	/**
-	 * Handles the events.
-	 */
-	handleEvent(): void {
-		this.#applyTheme();
+		for (const button of this.querySelectorAll("button")) button.removeEventListener("click", this.#setTheme);
+		this.#mediaQuery.removeEventListener("change", this.#applyTheme);
 	}
 
 	/**
 	 * Applies the application theme to the document.
 	 */
-	#applyTheme(): void {
+ 	readonly #applyTheme: () => void = () => {
 		const {appTheme} = this;
 		const bsTheme = appTheme == AppTheme.System ? (this.#mediaQuery.matches ? AppTheme.Dark : AppTheme.Light) : appTheme;
 		document.documentElement.dataset.bsTheme = bsTheme.toLowerCase();
-	}
+	};
 
 	/**
 	 * Changes the current application theme.
 	 * @param event The dispatched event.
 	 */
-	#setTheme(event: Event): void {
+	readonly #setTheme: (event: Event) => void = event => {
 		event.preventDefault();
 		const button = (event.target as HTMLElement).closest("button")!;
 		this.appTheme = button.dataset.theme! as AppTheme;
-	}
+	};
 }
 
 /**

package/src/Client/UI/FormExtensions.ts

@@ -0,0 +1,55 @@
+/**
+ * The types of form controls that are not text inputs.
+ */
+const nonTextualTypes = new Set<string>(["button", "checkbox", "file", "hidden", "image", "password", "radio", "range", "reset", "submit"]);
+
+/**
+ * Represents a form control.
+ */
+export type FormControl = HTMLInputElement|HTMLSelectElement|HTMLTextAreaElement;
+
+/**
+ * Gets all controls belonging to the specified form.
+ * @param form The form element.
+ * @returns The controls belonging to the specified form.
+ */
+export function getFormControls(form: HTMLFormElement): FormControl[] {
+	return Array.from(form.elements).filter(isFormControl);
+}
+
+/**
+ * Returns the first invalid control from the specified form.
+ * @param form The form element.
+ * @returns The first invalid control, or `null` if all controls are valid.
+ */
+export function invalidControl(form: HTMLFormElement): FormControl|null {
+	return form.querySelector(":not(fieldset):invalid");
+}
+
+/**
+ * Returns a value indicating whether the specified element is a form control.
+ * @param element The element to check.
+ * @returns `true` if the specified element is a form control, otherwise `false`.
+ */
+export function isFormControl(element: Element): element is FormControl {
+	return element instanceof HTMLInputElement || element instanceof HTMLSelectElement || element instanceof HTMLTextAreaElement;
+}
+
+/**
+ * Resets the validity of the specified element.
+ * @param element The element to process.
+ */
+export function resetValidity(element: Element): void {
+	if (element instanceof HTMLFormElement) getFormControls(element).forEach(control => control.setCustomValidity(""));
+	else if (isFormControl(element)) element.setCustomValidity("");
+}
+
+/**
+ * Removes whitespace from both ends of the value of the specified element.
+ * @param element The element to process.
+ */
+export function trimControl(element: Element): void {
+	if (element instanceof HTMLFormElement) getFormControls(element).forEach(trimControl);
+	else if (element instanceof HTMLInputElement && !nonTextualTypes.has(element.type)) element.value = element.value.trim();
+	else if (element instanceof HTMLTextAreaElement) element.value = element.value.trim();
+}

package/src/Client/UI/StorageArea.ts

@@ -0,0 +1,20 @@
+/**
+ * Identifies the web storage area.
+ */
+export const StorageArea = Object.freeze({
+
+	/**
+	 * Indicates the local storage.
+	 */
+	Local: "Local",
+
+	/**
+	 * Indicates the session storage.
+	 */
+	Session: "Session"
+});
+
+/**
+ * Identifies the web storage area.
+ */
+export type StorageArea = typeof StorageArea[keyof typeof StorageArea];

package/src/Client/UI/tsconfig.json

@@ -9,8 +9,5 @@
 		"outDir": "../../../lib/UI",
 		"rootDir": ".",
 		"tsBuildInfoFile": "../../../var/UI.tsbuildinfo"
-	},
-	"references": [
-		{"path": "../Base/tsconfig.json"}
-	]
+	}
 }

package/src/Client/tsconfig.json

@@ -3,6 +3,7 @@
 	"references": [
 		{"path": "Base/tsconfig.json"},
 		{"path": "Data/tsconfig.json"},
+		{"path": "Hosting/tsconfig.json"},
 		{"path": "Net/tsconfig.json"},
 		{"path": "UI/tsconfig.json"}
 	]

package/lib/Net/Http/HttpClient.d.ts

@@ -1,83 +0,0 @@
-/**
- * Performs HTTP requests.
- */
-export declare class HttpClient {
-    #private;
-    /**
-     * The base URL of the remote service.
-     */
-    readonly baseAddress: URL;
-    /**
-     * Creates a new HTTP client.
-     * @param options An object providing values to initialize this instance.
-     */
-    constructor(options?: HttpClientOptions);
-    /**
-     * Performs a DELETE request.
-     * @param url The URL of the resource to fetch.
-     * @param options The request options.
-     * @returns The server response.
-     */
-    delete(url?: string | URL, options?: RequestInit): Promise<Response>;
-    /**
-     * Performs a GET request.
-     * @param url The URL of the resource to fetch.
-     * @param options The request options.
-     * @returns The server response.
-     */
-    get(url?: string | URL, options?: RequestInit): Promise<Response>;
-    /**
-     * Performs a PATCH request.
-     * @param url The URL of the resource to fetch.
-     * @param body The request body.
-     * @param options The request options.
-     * @returns The server response.
-     */
-    patch(url?: string | URL, body?: unknown, options?: RequestInit): Promise<Response>;
-    /**
-     * Performs a POST request.
-     * @param url The URL of the resource to fetch.
-     * @param body The request body.
-     * @param options The request options.
-     * @returns The server response.
-     */
-    post(url?: string | URL, body?: unknown, options?: RequestInit): Promise<Response>;
-    /**
-     * Performs a PUT request.
-     * @param url The URL of the resource to fetch.
-     * @param body The request body.
-     * @param options The request options.
-     * @returns The server response.
-     */
-    put(url?: string | URL, body?: unknown, options?: RequestInit): Promise<Response>;
-}
-/**
- * Defines the options of a {@link HttpClient} instance.
- */
-export type HttpClientOptions = Partial<{
-    /**
-     * The base URL of the remote service.
-     */
-    baseUrl: string | URL;
-    /**
-     * The function returning the component used as loading indicator.
-     */
-    loadingIndicator: () => ILoadingIndicator | null;
-}>;
-/**
- * A component that shows up when an HTTP request starts, and hides when all concurrent HTTP requests are completed.
- */
-export interface ILoadingIndicator {
-    /**
-     * Starts the loading indicator.
-     */
-    start: () => void;
-    /**
-     * Stops the loading indicator.
-     * @param options Value indicating whether to force the loading indicator to stop.
-     */
-    stop: (options?: {
-        force?: boolean;
-    }) => void;
-}
-//# sourceMappingURL=HttpClient.d.ts.map

package/lib/Net/Http/HttpClient.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"HttpClient.d.ts","sourceRoot":"","sources":["../../../src/Client/Net/Http/HttpClient.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,qBAAa,UAAU;;IAEtB;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC;IAO1B;;;OAGG;gBACS,OAAO,GAAE,iBAAsB;IAM3C;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,GAAC,GAAG,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAIlE;;;;;OAKG;IACH,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,GAAC,GAAG,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI/D;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,GAAC,GAAG,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAIjF;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,GAAC,GAAG,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAIhF;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,GAAC,GAAG,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;CAiC/E;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC;IAEvC;;OAEG;IACH,OAAO,EAAE,MAAM,GAAC,GAAG,CAAC;IAEpB;;OAEG;IACH,gBAAgB,EAAE,MAAM,iBAAiB,GAAC,IAAI,CAAC;CAC/C,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAEjC;;OAEG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB;;;OAGG;IACH,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC,KAAK,IAAI,CAAC;CAC5C"}