@cedx/base 0.1.0

package/lib/UI/ThemeDropdown.js

@@ -0,0 +1,123 @@
+import { __decorate } from "tslib";
+import { AppTheme, themeIcon, themeLabel } from "#Html/AppTheme.js";
+import { MenuAlignment } from "#Html/MenuAlignment.js";
+import { html, LitElement } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+import { classMap } from "lit/directives/class-map.js";
+import { when } from "lit/directives/when.js";
+/**
+ * A dropdown menu for switching the color mode.
+ */
+let ThemeDropdown = class ThemeDropdown extends LitElement {
+    /**
+     * The media query used to check the system theme.
+     */
+    #mediaQuery;
+    /**
+     * Creates a new theme dropdown.
+     */
+    constructor() {
+        super();
+        /**
+         * The alignment of the dropdown menu.
+         */
+        this.alignment = MenuAlignment.End;
+        /**
+         * The label of the dropdown menu.
+         */
+        this.label = "";
+        /**
+         * The key of the storage entry providing the saved theme.
+         */
+        this.storageKey = "AppTheme";
+        /**
+         * The media query used to check the system theme.
+         */
+        this.#mediaQuery = matchMedia("(prefers-color-scheme: dark)");
+        const theme = localStorage.getItem(this.storageKey);
+        this.appTheme = Object.values(AppTheme).includes(theme) ? theme : AppTheme.System;
+    }
+    /**
+     * The current theme mode.
+     */
+    get theme() { return this.appTheme; }
+    set theme(value) {
+        localStorage.setItem(this.storageKey, this.appTheme = value);
+        this.#applyTheme();
+    }
+    /**
+     * Method invoked when this component is connected.
+     */
+    connectedCallback() {
+        super.connectedCallback();
+        this.#applyTheme();
+        this.#mediaQuery.addEventListener("change", this);
+    }
+    /**
+     * Method invoked when this component is disconnected.
+     */
+    disconnectedCallback() {
+        this.#mediaQuery.removeEventListener("change", this);
+        super.disconnectedCallback();
+    }
+    /**
+     * Handles the events.
+     */
+    handleEvent() {
+        this.#applyTheme();
+    }
+    /**
+     * Returns the node into which this component should render.
+     * @returns The node into which this component should render.
+     */
+    createRenderRoot() {
+        return this;
+    }
+    /**
+     * Renders this component.
+     * @returns The view template.
+     */
+    render() {
+        return html `
+			<li class="nav-item dropdown">
+				<a class="dropdown-toggle nav-link" data-bs-toggle="dropdown" href="#">
+					<i class="icon icon-fill">${themeIcon(this.appTheme)}</i>
+					${when(this.label, () => html `<span class="ms-1">${this.label}</span>`)}
+				</a>
+				<ul class="dropdown-menu ${classMap({ "dropdown-menu-end": this.alignment == MenuAlignment.End })}">
+					${Object.values(AppTheme).map(value => html `
+						<li>
+							<button class="dropdown-item d-flex align-items-center justify-content-between" @click=${() => this.theme = value}>
+								<span><i class="icon icon-fill me-1">${themeIcon(value)}</i> ${themeLabel(value)}</span>
+								${when(value == this.appTheme, () => html `<i class="icon ms-2">check</i>`)}
+							</button>
+						</li>
+					`)}
+				</ul>
+			</li>
+		`;
+    }
+    /**
+     * Applies the theme to the document.
+     */
+    #applyTheme() {
+        const theme = this.appTheme == AppTheme.System ? (this.#mediaQuery.matches ? AppTheme.Dark : AppTheme.Light) : this.appTheme;
+        document.documentElement.dataset.bsTheme = theme.toLowerCase();
+    }
+};
+__decorate([
+    property()
+], ThemeDropdown.prototype, "alignment", void 0);
+__decorate([
+    property()
+], ThemeDropdown.prototype, "label", void 0);
+__decorate([
+    property()
+], ThemeDropdown.prototype, "storageKey", void 0);
+__decorate([
+    state()
+], ThemeDropdown.prototype, "appTheme", void 0);
+ThemeDropdown = __decorate([
+    customElement("theme-dropdown")
+], ThemeDropdown);
+export { ThemeDropdown };

package/package.json

@@ -0,0 +1,59 @@
+{
+	"author": "Cédric Belin <cedx@outlook.com>",
+	"bugs": "https://github.com/cedx/base/issues",
+	"description": "Base library by Cédric Belin, full stack developer.",
+	"homepage": "https://github.com/cedx/base",
+	"license": "MIT",
+	"name": "@cedx/base",
+	"repository": "cedx/base",
+	"type": "module",
+	"version": "0.1.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.0",
+		"@types/serve-handler": "^6.1.4",
+		"chai": "^5.2.1",
+		"esbuild": "^0.25.8",
+		"globals": "^16.3.0",
+		"mocha": "^11.7.1",
+		"playwright": "^1.54.2",
+		"serve-handler": "^6.1.6",
+		"typedoc": "^0.28.9",
+		"typescript": "^5.9.2",
+		"typescript-eslint": "^8.39.0"
+	},
+	"engines": {
+		"node": ">=24.0.0"
+	},
+	"exports": {
+		"./*.js": {
+			"types": "./lib/*.d.ts",
+			"default": "./lib/*.js"
+		}
+	},
+	"files": [
+		"lib/",
+		"src/Client/"
+	],
+	"imports": {
+		"#Abstractions/*.js": "./lib/Abstractions/*.js",
+		"#Html/*.js": "./lib/Html/*.js"
+	},
+	"keywords": [
+		"belin",
+		"core",
+		"framework",
+		"library"
+	],
+	"peerDependencies": {
+		"bootstrap": ">=5.3.0",
+		"lit": ">=3.3.0",
+		"tslib": ">=2.8.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/Client/Abstractions/ILoadingIndicator.ts

@@ -0,0 +1,16 @@
+/**
+ * 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;
+}

package/src/Client/Abstractions/tsconfig.json

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

package/src/Client/Base/tsconfig.json

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

package/src/Client/DependencyInjection/Container.ts

@@ -0,0 +1,75 @@
+/**
+ * Provides a dependency container.
+ */
+export class Container {
+
+	/**
+	 * The registered factories.
+	 */
+	readonly #factories = new Map<ContainerToken, () => any>;
+
+	/**
+	 * The registered services.
+	 */
+	readonly #services = new Map<ContainerToken, any>;
+
+	/**
+	 * Removes the service registered with the specified identifier.
+	 * @param id The identification token.
+	 */
+	delete(id: ContainerToken): void {
+		this.#factories.delete(id);
+		this.#services.delete(id);
+	}
+
+	/**
+	 * Gets the service registered with the specified identifier.
+	 * @param id The identification token.
+	 * @returns The instance of the service registered with the specified identifier.
+	 * @throws `Error` if there is no factory registered with the specified identifier.
+	 */
+	get<T>(id: ContainerToken): T { // eslint-disable-line @typescript-eslint/no-unnecessary-type-parameters
+		if (!this.#services.has(id))
+			if (this.#factories.has(id)) this.set(id, this.#factories.get(id)!());
+			else if (typeof id == "function") this.set(id, Reflect.construct(id, []));
+			else throw Error("There is no factory registered with the specified identifier.");
+
+		return this.#services.get(id) as T;
+	}
+
+	/**
+	 * Gets a value indicating whether this container has a service registered with the specified identifier.
+	 * @param id The identification token.
+	 * @returns `true` if a service registered with the specified identifier exists in this container, otherwise `false`.
+	 */
+	has(id: ContainerToken): boolean {
+		return this.#factories.has(id) || this.#services.has(id);
+	}
+
+	/**
+	 * Registers a service factory with this container.
+	 * @param id The identification token.
+	 * @param factory The service factory.
+	 * @returns This instance.
+	 */
+	register(id: ContainerToken, factory: () => unknown): this {
+		this.#factories.set(id, factory);
+		return this;
+	}
+
+	/**
+	 * Registers a service instance with this container.
+	 * @param id The identification token.
+	 * @param service The service instance.
+	 * @returns This instance.
+	 */
+	set(id: ContainerToken, service: unknown): this {
+		this.#services.set(id, service);
+		return this;
+	}
+}
+
+/**
+ * A token identifying a service.
+ */
+export type ContainerToken = string|symbol|(new(...args: any[]) => any);

package/src/Client/DependencyInjection/tsconfig.json

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

package/src/Client/Html/AppTheme.ts

@@ -0,0 +1,51 @@
+/**
+ * Enumerates different themes an operating system or application can show.
+ */
+export const AppTheme = Object.freeze({
+
+	/**
+	 * The system predefined theme mode.
+	 */
+	System: "System",
+
+	/**
+	 * The light predefined theme mode.
+	 */
+	Light: "Light",
+
+	/**
+	 * The dark predefined theme mode.
+	 */
+	Dark: "Dark"
+});
+
+/**
+ * Enumerates different themes an operating system or application can show.
+ */
+export type AppTheme = typeof AppTheme[keyof typeof AppTheme];
+
+/**
+ * Gets the icon corresponding to the specified theme.
+ * @param theme The theme mode.
+ * @returns The icon corresponding to the specified theme.
+ */
+export function themeIcon(theme: AppTheme): string {
+	switch (theme) {
+		case AppTheme.Dark: return "dark_mode";
+		case AppTheme.Light: return "light_mode";
+		default: return "contrast";
+	}
+}
+
+/**
+ * Gets the label corresponding to the specified theme.
+ * @param theme The theme mode.
+ * @returns The label corresponding to the specified theme.
+ */
+export function themeLabel(theme: AppTheme): string {
+	switch (theme) {
+		case AppTheme.Dark: return "Sombre";
+		case AppTheme.Light: return "Clair";
+		default: return "Auto";
+	}
+}

package/src/Client/Html/MenuAlignment.ts

@@ -0,0 +1,20 @@
+/**
+ * Defines the alignment of a dropdown menu.
+ */
+export const MenuAlignment = Object.freeze({
+
+	/**
+	 * The dropdown menu is right aligned.
+	 */
+	End: "End",
+
+	/**
+	 * The dropdown menu is left aligned.
+	 */
+	Start: "Start"
+});
+
+/**
+ * Defines the alignment of a dropdown menu.
+ */
+export type MenuAlignment = typeof MenuAlignment[keyof typeof MenuAlignment];

package/src/Client/Html/ViewportScroller.ts

@@ -0,0 +1,89 @@
+/**
+ * Defines the scrolling options.
+ */
+export type ScrollOptions = Partial<{
+
+	/**
+	 * Value indicating whether scrolling is instant or animates smoothly.
+	 */
+	behavior: ScrollBehavior
+}>;
+
+/**
+ * Manages the scroll position.
+ */
+export class ViewportScroller {
+
+	/**
+	 * The top offset used when scrolling to an element.
+	 */
+	#scrollOffset = -1;
+
+	/**
+	 * The function returning the element used as viewport.
+	 */
+	readonly #viewport: () => Element;
+
+	/**
+	 * Creates a new viewport scroller.
+	 * @param viewport A function that returns the element used as viewport.
+	 */
+	constructor(viewport: () => Element = () => document.scrollingElement ?? document.documentElement) {
+		this.#viewport = viewport;
+	}
+
+	/**
+	 * The top offset used when scrolling to an element.
+	 */
+	get scrollOffset(): number {
+		if (this.#scrollOffset < 0) {
+			const fontSize = parseInt(getComputedStyle(document.body).fontSize);
+			this.#scrollOffset = Number.isNaN(fontSize) ? 0 : fontSize * 2;
+
+			const navbarHeight = parseInt(getComputedStyle(document.documentElement).getPropertyValue("--navbar-height"));
+			this.#scrollOffset += Number.isNaN(navbarHeight) ? 0 : navbarHeight;
+		}
+
+		const actionBar: HTMLElement|null = document.body.querySelector("action-bar");
+		return this.#scrollOffset + (actionBar?.offsetHeight ?? 0);
+	}
+
+	/**
+	 * Scrolls to the specified anchor.
+	 * @param anchor The identifier or name of an elment.
+	 * @param options Value indicating whether scrolling is instant or animates smoothly.
+	 */
+	scrollToAnchor(anchor: string, options: ScrollOptions = {}): void {
+		const element = document.getElementById(anchor) ?? document.body.querySelector(`[name="${anchor}"]`);
+		if (element) this.scrollToElement(element, options);
+	}
+
+	/**
+	 * Scrolls to the specified element.
+	 * @param element The element to scroll to.
+	 * @param options Value indicating whether scrolling is instant or animates smoothly.
+	 */
+	scrollToElement(element: Element, options: ScrollOptions = {}): void {
+		const {left, top} = element.getBoundingClientRect();
+		const {scrollLeft, scrollTop} = this.#viewport();
+		this.scrollToPosition(left + scrollLeft, top + scrollTop - this.scrollOffset, options);
+	}
+
+	/**
+	 * Scrolls to the specified position.
+	 * @param x The pixel along the horizontal axis.
+	 * @param y The pixel along the vertical axis.
+	 * @param options Value indicating whether scrolling is instant or animates smoothly.
+	 */
+	scrollToPosition(x: number, y: number, options: ScrollOptions = {}): void {
+		this.#viewport().scrollTo({left: x, top: y, behavior: options.behavior ?? "auto"});
+	}
+
+	/**
+	 * Scrolls to the top.
+	 * @param options Value indicating whether scrolling is instant or animates smoothly.
+	 */
+	scrollToTop(options: ScrollOptions = {}): void {
+		this.scrollToPosition(0, 0, options);
+	}
+}

package/src/Client/Html/tsconfig.json

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

package/src/Client/Http/HttpClient.ts

@@ -0,0 +1,127 @@
+import type {ILoadingIndicator} from "#Abstractions/ILoadingIndicator.js";
+import {HttpError} from "./HttpError.js";
+
+/**
+ * Performs HTTP requests.
+ */
+export class HttpClient {
+
+	/**
+	 * The base URL of the remote service.
+	 */
+	readonly baseUrl: URL;
+
+	/**
+	 * The function returning the component used as loading indicator.
+	 */
+	readonly #loadingIndicator: () => ILoadingIndicator|null;
+
+	/**
+	 * Creates a new HTTP client.
+	 * @param options An object providing values to initialize this instance.
+	 */
+	constructor(options: HttpClientOptions = {}) {
+		const url = options.baseUrl ? (options.baseUrl instanceof URL ? options.baseUrl.href : options.baseUrl) : document.baseURI;
+		this.baseUrl = new URL(url.endsWith("/") ? url : `${url}/`);
+		this.#loadingIndicator = options.loadingIndicator ?? (() => document.body.querySelector("loading-indicator") as ILoadingIndicator|null);
+	}
+
+	/**
+	 * 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> {
+		return this.#fetch("DELETE", url, null, options);
+	}
+
+	/**
+	 * 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> {
+		return this.#fetch("GET", url, null, options);
+	}
+
+	/**
+	 * 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> {
+		return this.#fetch("PATCH", url, body, options);
+	}
+
+	/**
+	 * 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> {
+		return this.#fetch("POST", url, body, options);
+	}
+
+	/**
+	 * 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> {
+		return this.#fetch("PUT", url, body, options);
+	}
+
+	/**
+	 * Performs a custom HTTP request.
+	 * @param method The HTTP method.
+	 * @param url The URL of the resource to fetch.
+	 * @param body The request body.
+	 * @param options The request options.
+	 * @returns The server response.
+	 */
+	async #fetch(method: string, url: string|URL = "", body: unknown = null, options: RequestInit = {}): Promise<Response> {
+		const headers = new Headers(options.headers);
+		if (!headers.has("accept")) headers.set("accept", "application/json");
+
+		if (body && !(body instanceof Blob || body instanceof FormData || body instanceof URLSearchParams)) {
+			if (typeof body != "string") body = JSON.stringify(body);
+			if (!headers.has("content-type")) headers.set("content-type", "application/json");
+		}
+
+		const loadingIndicator = this.#loadingIndicator();
+		try {
+			loadingIndicator?.start();
+			const request = new Request(new URL(url, this.baseUrl), {...options, method, headers, body} as RequestInit);
+			const response = await fetch(request);
+			if (!response.ok) throw new HttpError(response);
+			return response;
+		}
+		finally {
+			loadingIndicator?.stop();
+		}
+	}
+}
+
+/**
+ * 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;
+}>;

package/src/Client/Http/HttpError.ts

@@ -0,0 +1,75 @@
+import {StatusCodes} from "./StatusCodes.js";
+
+/**
+ * An object thrown when an HTTP error occurs.
+ */
+export class HttpError extends globalThis.Error {
+
+	/**
+	 * The validation errors.
+	 */
+	#validationErrors: Map<string, string>|null = null;
+
+	/**
+	 * Creates a new HTTP error.
+	 * @param response The server response.
+	 */
+	constructor(response: Response) {
+		super(`${response.status} ${response.statusText}`, {cause: response});
+		this.name = "HttpError";
+	}
+
+	/**
+	 * The server response.
+	 */
+	override get cause(): Response {
+		return super.cause as Response;
+	}
+
+	/**
+	 * Value indicating whether the response's status code is between 400 and 499.
+	 */
+	get isClientError(): boolean {
+		const {status} = this;
+		return status >= 400 && status < 500;
+	}
+
+	/**
+	 * Value indicating whether the response's status code is between 500 and 599.
+	 */
+	get isServerError(): boolean {
+		const {status} = this;
+		return status >= 500 && status < 600;
+	}
+
+	/**
+	 * The response's status code.
+	 */
+	get status(): StatusCodes {
+		return this.cause.status as StatusCodes;
+	}
+
+	/**
+	 * The validation errors.
+	 */
+	get validationErrors(): Promise<Map<string, string>> {
+		return this.#validationErrors
+			? Promise.resolve(this.#validationErrors)
+			: this.#parseValidationErrors().then(errors => this.#validationErrors = errors);
+	}
+
+	/**
+	 * Parses the validation errors returned in the body of the specified response.
+	 * @returns The validation errors provided by the response body.
+	 */
+	async #parseValidationErrors(): Promise<Map<string, string>> {
+		try {
+			const statuses = new Set<StatusCodes>([StatusCodes.BadRequest, StatusCodes.UnprocessableContent]);
+			const ignoreBody = this.cause.bodyUsed || !statuses.has(this.status);
+			return new Map(ignoreBody ? [] : Object.entries(await this.cause.json() as Record<string, string>));
+		}
+		catch {
+			return new Map;
+		}
+	}
+}