@cedx/base 0.6.0 → 0.7.0

package/src/Client/{Http/HttpError.ts → Net/Http/HttpRequestError.ts}

@@ -1,9 +1,9 @@
-import {StatusCodes} from "./StatusCodes.js";
+import {StatusCode} from "./StatusCode.js";
 
 /**
- * An object thrown when an HTTP error occurs.
+ * An error thrown by the HTTP client.
  */
-export class HttpError extends globalThis.Error {
+export class HttpRequestError extends globalThis.Error {
 
 	/**
 	 * The validation errors.
@@ -12,41 +12,41 @@ export class HttpError extends globalThis.Error {
 
 	/**
 	 * Creates a new HTTP error.
-	 * @param response The server response.
+	 * @param response The HTTP response.
 	 */
 	constructor(response: Response) {
 		super(`${response.status} ${response.statusText}`, {cause: response});
-		this.name = "HttpError";
+		this.name = "HttpRequestError";
 	}
 
 	/**
-	 * The server response.
+	 * The HTTP response.
 	 */
 	override get cause(): Response {
 		return super.cause as Response;
 	}
 
 	/**
-	 * Value indicating whether the response's status code is between 400 and 499.
+	 * Value indicating whether the HTTP status code is between 400 and 499.
 	 */
 	get isClientError(): boolean {
-		const {status} = this;
-		return status >= 400 && status < 500;
+		const {statusCode} = this;
+		return statusCode >= 400 && statusCode < 500;
 	}
 
 	/**
-	 * Value indicating whether the response's status code is between 500 and 599.
+	 * Value indicating whether the HTTP status code is between 500 and 599.
 	 */
 	get isServerError(): boolean {
-		const {status} = this;
-		return status >= 500 && status < 600;
+		const {statusCode} = this;
+		return statusCode >= 500 && statusCode < 600;
 	}
 
 	/**
-	 * The response's status code.
+	 * The HTTP status code.
 	 */
-	get status(): StatusCodes {
-		return this.cause.status as StatusCodes;
+	get statusCode(): StatusCode {
+		return this.cause.status as StatusCode;
 	}
 
 	/**
@@ -64,8 +64,8 @@ export class HttpError extends globalThis.Error {
 	 */
 	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);
+			const statuses: StatusCode[] = [StatusCode.BadRequest, StatusCode.UnprocessableContent];
+			const ignoreBody = this.cause.bodyUsed || !statuses.includes(this.statusCode);
 			return new Map(ignoreBody ? [] : Object.entries(await this.cause.json() as Record<string, string>));
 		}
 		catch {

package/src/Client/Net/Http/StatusCode.ts

@@ -0,0 +1,150 @@
+/**
+ * Provides common HTTP status codes.
+ */
+export const StatusCode = Object.freeze({
+
+	/**
+	 * The `OK` status code.
+	 */
+	OK: 200,
+
+	/**
+	 * The `Created` status code.
+	 */
+	Created: 201,
+
+	/**
+	 * The `No Content` status code.
+	 */
+	NoContent: 204,
+
+	/**
+	 * The `Moved Permanently` status code.
+	 */
+	MovedPermanently: 301,
+
+	/**
+	 * The `Found` status code.
+	 */
+	Found: 302,
+
+	/**
+	 * The `Not Modified` status code.
+	 */
+	NotModified: 304,
+
+	/**
+	 * The `Temporary Redirect` status code.
+	 */
+	TemporaryRedirect: 307,
+
+	/**
+	 * The `Permanent Redirect` status code.
+	 */
+	PermanentRedirect: 308,
+
+	/**
+	 * The `Bad Request` status code.
+	 */
+	BadRequest: 400,
+
+	/**
+	 * The `Unauthorized` status code.
+	 */
+	Unauthorized: 401,
+
+	/**
+	 * The `Payment Required` status code.
+	 */
+	PaymentRequired: 402,
+
+	/**
+	 * The `Forbidden` status code.
+	 */
+	Forbidden: 403,
+
+	/**
+	 * The `Not Found` status code.
+	 */
+	NotFound: 404,
+
+	/**
+	 * The `Method Not Allowed` status code.
+	 */
+	MethodNotAllowed: 405,
+
+	/**
+	 * The `Not Acceptable` status code.
+	 */
+	NotAcceptable: 406,
+
+	/**
+	 * The `Request Timeout` status code.
+	 */
+	RequestTimeout: 408,
+
+	/**
+	 * The `Conflict` status code.
+	 */
+	Conflict: 409,
+
+	/**
+	 * The `Payload Too Large` status code.
+	 */
+	PayloadTooLarge: 413,
+
+	/**
+	 * The `Unsupported Media Type` status code.
+	 */
+	UnsupportedMediaType: 415,
+
+	/**
+	 * The `Authentication Timeout` status code.
+	 */
+	AuthenticationTimeout: 419,
+
+	/**
+	 * The `Unprocessable Content` status code.
+	 */
+	UnprocessableContent: 422,
+
+	/**
+	 * The `Too Many Requests` status code.
+	 */
+	TooManyRequests: 429,
+
+	/**
+	 * The `Internal Server Error` status code.
+	 */
+	InternalServerError: 500,
+
+	/**
+	 * The `Not Implemented` status code.
+	 */
+	NotImplemented: 501,
+
+	/**
+	 * The `Bad Gateway` status code.
+	 */
+	BadGateway: 502,
+
+	/**
+	 * The `Service Unavailable` status code.
+	 */
+	ServiceUnavailable: 503,
+
+	/**
+	 * The `Gateway Timeout` status code.
+	 */
+	GatewayTimeout: 504,
+
+	/**
+	 * The `Bandwidth Limit Exceeded` status
+	 */
+	BandwidthLimitExceeded: 509
+});
+
+/**
+ * Provides common HTTP status codes.
+ */
+export type StatusCode = typeof StatusCode[keyof typeof StatusCode];

package/src/Client/Net/Mime/DispositionType.ts

@@ -0,0 +1,20 @@
+/**
+ * Provides the strings used to specify the disposition type.
+ */
+export const DispositionType = Object.freeze({
+
+	/**
+	 * The `attachment` disposition type.
+	 */
+	Attachment: "attachment",
+
+	/**
+	 * The `inline` disposition type.
+	 */
+	Inline: "inline"
+});
+
+/**
+ * Provides the strings used to specify the disposition type.
+ */
+export type DispositionType = typeof DispositionType[keyof typeof DispositionType];

package/src/Client/Net/Mime/MediaType.ts

@@ -0,0 +1,185 @@
+/**
+ * Provides the strings used to specify the media type.
+ */
+export const MediaType = Object.freeze({
+
+	/**
+	 * Specifies the kind of application data.
+	 */
+	Application: Object.freeze({
+
+		/**
+		 * Specifies that the application data consists of url-encoded key-value pairs.
+		 */
+		FormUrlEncoded: "application/x-www-form-urlencoded",
+
+		/**
+		 * Specifies that the application data is in gzip format.
+		 */
+		GZip: "application/gzip",
+
+		/**
+		 * Specifies that the application data is in JSON format.
+		 */
+		Json: "application/json",
+
+		/**
+		 * Specifies that the application data is in Web Application Manifest.
+		 */
+		Manifest: "application/manifest+json",
+
+		/**
+		 * Specifies that the application data is not interpreted.
+		 */
+		Octet: "application/octet-stream",
+
+		/**
+		 * Specifies that the application data is in Portable Document Format (PDF).
+		 */
+		Pdf: "application/pdf",
+
+		/**
+		 * Specifies that the application data is a SOAP document.
+		 */
+		Soap: "application/soap+xml",
+
+		/**
+		 * Specifies that the application data is in WASM format.
+		 */
+		Wasm: "application/wasm",
+
+		/**
+		 * Specifies that the application data is in XML format.
+		 */
+		Xml: "application/xml",
+
+		/**
+		 * Specifies that the application data is compressed.
+		 */
+		Zip: "application/zip"
+	}),
+
+	/**
+	 * Specifies the kind of font data.
+	 */
+	Font: Object.freeze({
+
+		/**
+		 * Specifies that the font data is in TrueType font (TTF) format.
+		 */
+		Ttf: "font/ttf",
+
+		/**
+		 * Specifies that the font data is in WOFF format.
+		 */
+		Woff: "font/woff",
+
+		/**
+		 * Specifies that the font data is in WOFF2 format.
+		 */
+		Woff2: "font/woff2"
+	}),
+
+	/**
+	 * Specifies the kind of image data.
+	 */
+	Image: Object.freeze({
+
+		/**
+		 * Specifies that the image data is in AVIF format.
+		 */
+		Avif: "image/avif",
+
+		/**
+		 * Specifies that the image data is in GIF format.
+		 */
+		Gif: "image/gif",
+
+		/**
+		 * Specifies that the image data is in ICO format.
+		 */
+		Icon: "image/x-icon",
+
+		/**
+		 * Specifies that the image data is in JPEG format.
+		 */
+		Jpeg: "image/jpeg",
+
+		/**
+		 * Specifies that the image data is in PNG format.
+		 */
+		Png: "image/png",
+
+		/**
+		 * Specifies that the image data is in SVG format.
+		 */
+		Svg: "image/svg+xml",
+
+		/**
+		 * Specifies that the image data is in WEBP format.
+		 */
+		WebP: "image/webp"
+	}),
+
+	/**
+	 * Specifies the kind of multipart data.
+	 */
+	Multipart: Object.freeze({
+
+		/**
+		 * Specifies that the multipart data is in form data format.
+		 */
+		FormData: "multipart/form-data",
+
+		/**
+		 * Specifies that the multipart data is in mixed format.
+		 */
+		Mixed: "multipart/mixed"
+	}),
+
+	/**
+	 * Specifies the kind of text data.
+	 */
+	Text: Object.freeze({
+
+		/**
+		 * Specifies that the text data is in CSS format.
+		 */
+		Css: "text/css",
+
+		/**
+		 * Specifies that the text data is in CSV format.
+		 */
+		Csv: "text/csv",
+
+		/**
+		 * Specifies that the text data is in event stream format.
+		 */
+		EventStream: "text/event-stream",
+
+		/**
+		 * Specifies that the text data is in HTML format.
+		 */
+		Html: "text/html",
+
+		/**
+		 * Specifies that the text data is in JavaScript format.
+		 */
+		JavaScript: "text/javascript",
+
+		/**
+		 * Specifies that the text data is in Markdown format.
+		 */
+		Markdown: "text/markdown",
+
+		/**
+		 * Specifies that the text data is in plain text format.
+		 */
+		Plain: "text/plain",
+
+		/**
+		 * Specifies that the text data is in XML format.
+		 */
+		Xml: "text/xml"
+	})
+});

package/src/Client/{Abstractions → Net}/tsconfig.json

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

package/src/Client/{Html → UI}/AppTheme.ts

@@ -4,17 +4,17 @@
 export const AppTheme = Object.freeze({
 
 	/**
-	 * The system predefined theme mode.
+	 * The system theme.
 	 */
 	System: "System",
 
 	/**
-	 * The light predefined theme mode.
+	 * The light theme.
 	 */
 	Light: "Light",
 
 	/**
-	 * The dark predefined theme mode.
+	 * The dark theme.
 	 */
 	Dark: "Dark"
 });

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

@@ -0,0 +1,34 @@
+import {LitElement, type CSSResultGroup} from "lit";
+
+/**
+ * Optional base class for UI components. Alternatively, components may extend {@link LitElement} directly.
+ */
+export abstract class ComponentBase extends LitElement {
+
+	/**
+	 * The component styles.
+	 */
+	static override styles: CSSResultGroup = [document.adoptedStyleSheets];
+
+	/**
+	 * Value indicating whether a shadow DOM tree should be attached to this component.
+	 */
+	readonly #attachShadow: boolean;
+
+	/**
+	 * Creates a new component.
+	 * @param options Value indicating whether a shadow DOM tree should be attached to this component.
+	 */
+	constructor(options: {attachShadow?: boolean} = {}) {
+		super();
+		this.#attachShadow = options.attachShadow ?? false;
+	}
+
+	/**
+	 * Returns the node into which this component should render.
+	 * @returns The node into which this component should render.
+	 */
+	protected override createRenderRoot(): DocumentFragment|HTMLElement {
+		return this.#attachShadow ? super.createRenderRoot() : this;
+	}
+}

package/src/Client/UI/{LoadingIndicator.ts → Components/LoadingIndicator.ts}

@@ -1,9 +1,7 @@
-import type {ILoadingIndicator} from "#Abstractions/ILoadingIndicator.js";
-
 /**
  * A component that shows up when an HTTP request starts, and hides when all concurrent HTTP requests are completed.
  */
-export class LoadingIndicator extends HTMLElement implements ILoadingIndicator {
+export class LoadingIndicator extends HTMLElement {
 
 	/**
 	 * The number of concurrent HTTP requests.

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

@@ -0,0 +1,163 @@
+import {AppTheme, getIcon} from "../AppTheme.js";
+import {MenuAlignment} from "../MenuAlignment.js";
+
+/**
+ * A dropdown menu for switching the application theme.
+ */
+export class ThemeDropdown extends HTMLElement {
+
+	/**
+	 * The list of observed attributes.
+	 */
+	static readonly observedAttributes = ["alignment", "apptheme", "label"];
+
+	/**
+	 * The media query used to check the application theme.
+	 */
+	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.
+	 */
+	static {
+		customElements.define("theme-dropdown", this);
+	}
+
+	/**
+	 * The alignment of the dropdown menu.
+	 */
+	get alignment(): MenuAlignment {
+		const value = this.getAttribute("alignment") as MenuAlignment;
+		return Object.values(MenuAlignment).includes(value) ? value : MenuAlignment.End;
+	}
+	set alignment(value: MenuAlignment) {
+		this.setAttribute("alignment", value);
+	}
+
+	/**
+	 * The current application theme.
+	 */
+	get appTheme(): AppTheme {
+		const value = this.getAttribute("apptheme") as AppTheme;
+		return Object.values(AppTheme).includes(value) ? value : AppTheme.System;
+	}
+	set appTheme(value: AppTheme) {
+		this.setAttribute("apptheme", value);
+		localStorage.setItem(this.storageKey, this.appTheme);
+	}
+
+	/**
+	 * The label of the dropdown menu.
+	 */
+	get label(): string {
+		const value = this.getAttribute("label") ?? "";
+		return value.trim() || "Thème";
+	}
+	set label(value: string) {
+		this.setAttribute("label", value);
+	}
+
+	/**
+	 * The key of the storage entry providing the saved application theme.
+	 */
+	get storageKey(): string {
+		const value = this.getAttribute("storagekey") ?? "";
+		return value.trim() || "AppTheme";
+	}
+	set storageKey(value: string) {
+		this.setAttribute("storagekey", value);
+	}
+
+	/**
+	 * Method invoked when an attribute has been changed.
+	 * @param attribute The attribute name.
+	 * @param oldValue The previous attribute value.
+	 * @param newValue The new attribute value.
+	 */
+	attributeChangedCallback(attribute: string, oldValue: string|null, newValue: string|null): void {
+		if (newValue != oldValue) switch (attribute) {
+			case "alignment": {
+				const alignment = Object.values(MenuAlignment).includes(newValue as MenuAlignment) ? newValue as MenuAlignment : MenuAlignment.End;
+				const {classList} = this.querySelector(".dropdown-menu")!;
+				if (alignment == MenuAlignment.End) classList.add("dropdown-menu-end");
+				else classList.remove("dropdown-menu-end");
+				break;
+			}
+			case "apptheme": {
+				const appTheme = Object.values(AppTheme).includes(newValue as AppTheme) ? newValue as AppTheme : AppTheme.System;
+				this.querySelector(".dropdown-toggle > .icon")!.textContent = getIcon(appTheme);
+				this.querySelector(`button[data-theme="${appTheme}"]`)!.appendChild(this.querySelector(".dropdown-item > .icon")!);
+				this.#applyTheme();
+				break;
+			}
+			case "label": {
+				this.querySelector(".dropdown-toggle > span")!.textContent = (newValue ?? "").trim() || "Thème";
+				break;
+			}
+			// No default
+		}
+	}
+
+	/**
+	 * Method invoked when this component is connected.
+	 */
+	connectedCallback(): void {
+		this.#mediaQuery.addEventListener("change", this);
+		const appTheme = localStorage.getItem(this.storageKey) as AppTheme|null;
+		if (appTheme) this.setAttribute("apptheme", appTheme);
+	}
+
+	/**
+	 * Method invoked when this component is disconnected.
+	 */
+	disconnectedCallback(): void {
+		this.#mediaQuery.removeEventListener("change", this);
+	}
+
+	/**
+	 * Handles the events.
+	 */
+	handleEvent(): void {
+		this.#applyTheme();
+	}
+
+	/**
+	 * Applies the application theme to the document.
+	 */
+	#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 {
+		event.preventDefault();
+		const button = (event.target as HTMLElement).closest("button")!;
+		this.appTheme = button.dataset.theme! as AppTheme;
+	}
+}
+
+/**
+ * Declaration merging.
+ */
+declare global {
+
+	/**
+	 * The map of HTML tag names.
+	 */
+	interface HTMLElementTagNameMap {
+		"theme-dropdown": ThemeDropdown;
+	}
+}

package/src/Client/UI/MenuAlignment.ts

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