@cedx/base 0.5.0 → 0.7.0

package/lib/UI/Context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Context.d.ts","sourceRoot":"","sources":["../../src/Client/UI/Context.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,OAAO;IAEnB;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;EAEF,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,MAAM,OAAO,OAAO,CAAC,CAAC;AAE3D;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAOhD"}

package/lib/UI/MenuAlignment.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Defines the alignment of a dropdown menu.
+ */
+export declare const MenuAlignment: Readonly<{
+    /**
+     * 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];
+//# sourceMappingURL=MenuAlignment.d.ts.map

package/lib/UI/MenuAlignment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MenuAlignment.d.ts","sourceRoot":"","sources":["../../src/Client/UI/MenuAlignment.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,aAAa;IAEzB;;OAEG;;IAGH;;OAEG;;EAEF,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC"}

package/lib/UI/MenuAlignment.js

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

package/lib/{Html → UI}/ViewportScroller.d.ts

@@ -23,7 +23,7 @@ export declare class ViewportScroller {
     get scrollOffset(): number;
     /**
      * Scrolls to the specified anchor.
-     * @param anchor The identifier or name of an elment.
+     * @param anchor The identifier or name of an element.
      * @param options Value indicating whether scrolling is instant or animates smoothly.
      */
     scrollToAnchor(anchor: string, options?: ScrollOptions): void;

package/lib/UI/ViewportScroller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ViewportScroller.d.ts","sourceRoot":"","sources":["../../src/Client/UI/ViewportScroller.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC;IAEnC;;OAEG;IACH,QAAQ,EAAE,cAAc,CAAA;CACxB,CAAC,CAAC;AAEH;;GAEG;AACH,qBAAa,gBAAgB;;IAY5B;;;OAGG;gBACS,QAAQ,GAAE,MAAM,OAAqE;IAIjG;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAWzB;IAED;;;;OAIG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,IAAI;IAKjE;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,aAAkB,GAAG,IAAI;IAMpE;;;;;OAKG;IACH,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,IAAI;IAIzE;;;OAGG;IACH,WAAW,CAAC,OAAO,GAAE,aAAkB,GAAG,IAAI;CAG9C"}

package/lib/{Html → UI}/ViewportScroller.js

@@ -22,21 +22,21 @@ export class ViewportScroller {
      */
     get scrollOffset() {
         if (this.#scrollOffset < 0) {
-            const fontSize = parseInt(getComputedStyle(document.body).fontSize);
+            const fontSize = Number.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 navbar = document.body.querySelector(".navbar");
+            this.#scrollOffset += (navbar?.offsetHeight ?? 0);
         }
-        const actionBar = document.body.querySelector("action-bar");
+        const actionBar = document.body.querySelector("action-bar, .action-bar");
         return this.#scrollOffset + (actionBar?.offsetHeight ?? 0);
     }
     /**
      * Scrolls to the specified anchor.
-     * @param anchor The identifier or name of an elment.
+     * @param anchor The identifier or name of an element.
      * @param options Value indicating whether scrolling is instant or animates smoothly.
      */
     scrollToAnchor(anchor, options = {}) {
-        const element = document.getElementById(anchor) ?? document.body.querySelector(`[name="${anchor}"]`);
+        const element = document.getElementById(anchor) ?? this.#viewport().querySelector(`[name="${anchor}"]`);
         if (element)
             this.scrollToElement(element, options);
     }

package/package.json

@@ -7,7 +7,7 @@
 	"name": "@cedx/base",
 	"repository": "cedx/base",
 	"type": "module",
-	"version": "0.5.0",
+	"version": "0.7.0",
 	"devDependencies": {
 		"@playwright/browser-chromium": "^1.54.2",
 		"@types/bootstrap": "^5.2.10",
@@ -16,14 +16,14 @@
 		"@types/node": "^24.2.1",
 		"@types/serve-handler": "^6.1.4",
 		"chai": "^5.2.1",
-		"esbuild": "^0.25.8",
+		"esbuild": "^0.25.9",
 		"globals": "^16.3.0",
 		"mocha": "^11.7.1",
 		"playwright": "^1.54.2",
 		"serve-handler": "^6.1.6",
-		"typedoc": "^0.28.9",
+		"typedoc": "^0.28.10",
 		"typescript": "^5.9.2",
-		"typescript-eslint": "^8.39.0"
+		"typescript-eslint": "^8.39.1"
 	},
 	"engines": {
 		"node": ">=24.0.0"
@@ -39,9 +39,7 @@
 		"src/Client/"
 	],
 	"imports": {
-		"#Abstractions/*.js": "./lib/Abstractions/*.js",
-		"#Base/*.js": "./lib/*.js",
-		"#Html/*.js": "./lib/Html/*.js"
+		"#Base/*.js": "./lib/*.js"
 	},
 	"keywords": [
 		"belin",
@@ -50,7 +48,8 @@
 		"library"
 	],
 	"peerDependencies": {
-		"bootstrap": ">=5.3.0"
+		"bootstrap": ">=5.3.0",
+		"lit": ">=3.3.0"
 	},
 	"publishConfig": {
 		"access": "public"

package/src/Client/Data/PaginatedList.ts

@@ -0,0 +1,47 @@
+import {Pagination} from "./Pagination.js";
+
+/**
+ * A list with information relevant to the pagination of its items.
+ */
+export class PaginatedList<T> extends Array<T> {
+
+	/**
+	 * The information relevant to the pagination of the list items.
+	 */
+	pagination: Pagination;
+
+	/**
+	 * Creates a new paginated list.
+	 * @param options An object providing values to initialize this instance.
+	 */
+	constructor(options: PaginatedListOptions<T> = {}) {
+		super();
+		for (const item of options.items ?? []) this.push(item);
+		this.pagination = options.pagination ?? new Pagination;
+	}
+
+	/**
+	 * Creates an empty paginated list.
+	 * @param itemsPerPage The number of items per page.
+	 * @returns An empty paginated list with the specified number of items per page.
+	 */
+	static empty<T>(itemsPerPage: number): PaginatedList<T> {
+		return new this({pagination: new Pagination({itemsPerPage})});
+	}
+}
+
+/**
+ * Defines the options of a {@link PaginatedList} instance.
+ */
+export type PaginatedListOptions<T> = Partial<{
+
+	/**
+	 * The list items.
+	 */
+	items: T[];
+
+	/**
+	 * The information relevant to the pagination of the list items.
+	 */
+	pagination: Pagination;
+}>;

package/src/Client/Data/Pagination.ts

@@ -0,0 +1,136 @@
+/**
+ * Represents information relevant to the pagination of data items.
+ */
+export class Pagination {
+
+	/**
+	 * The one-based current page number.
+	 */
+	#currentPageIndex!: number;
+
+	/**
+	 * The number of items per page.
+	 */
+	#itemsPerPage!: number;
+
+	/**
+	 * The total number of items.
+	 */
+	#totalItemCount!: number;
+
+	/**
+	 * Creates a new pagination.
+	 * @param options An object providing values to initialize this instance.
+	 */
+	constructor(options: PaginationOptions = {}) {
+		this.currentPageIndex = options.currentPageIndex ?? 1;
+		this.itemsPerPage = options.itemsPerPage ?? 25;
+		this.totalItemCount = options.totalItemCount ?? 0;
+	}
+
+	/**
+	 * The one-based current page number.
+	 */
+	get currentPageIndex(): number {
+		return this.#currentPageIndex;
+	}
+	set currentPageIndex(value: number) {
+		this.#currentPageIndex = Math.max(1, value);
+	}
+
+	/**
+	 * Value indicating whether a next page exists.
+	 */
+	get hasNextPage(): boolean {
+		return this.#currentPageIndex < this.lastPageIndex;
+	}
+
+	/**
+	 * Value indicating whether a previous page exists.
+	 */
+	get hasPreviousPage(): boolean {
+		return this.#currentPageIndex > 1;
+	}
+
+	/**
+	 * The number of items per page.
+	 */
+	get itemsPerPage(): number {
+		return this.#itemsPerPage;
+	}
+	set itemsPerPage(value: number) {
+		this.#itemsPerPage = Math.max(1, Math.min(1000, value));
+	}
+
+	/**
+	 * The one-based last page number.
+	 */
+	get lastPageIndex(): number {
+		return this.#totalItemCount > 0 ? Math.ceil(this.#totalItemCount / this.#itemsPerPage) : 1;
+	}
+
+	/**
+	 * The data limit.
+	 */
+	get limit(): number {
+		return this.#itemsPerPage;
+	}
+
+	/**
+	 * The data offset.
+	 */
+	get offset(): number {
+		return (this.#currentPageIndex - 1) * this.#itemsPerPage;
+	}
+
+	/**
+	 * The search parameters corresponding to this object.
+	 */
+	get searchParams(): URLSearchParams {
+		return new URLSearchParams({page: this.#currentPageIndex.toString(), perPage: this.#itemsPerPage.toString()});
+	}
+
+	/**
+	 * The total number of items.
+	 */
+	get totalItemCount(): number {
+		return this.#totalItemCount;
+	}
+	set totalItemCount(value: number) {
+		this.#totalItemCount = Math.max(0, value);
+	}
+
+	/**
+	 * Creates a new pagination from the HTTP headers of the specified response.
+	 * @param response A server response.
+	 * @returns The pagination corresponding to the HTTP headers of the specified response.
+	 */
+	static fromResponse(response: Response): Pagination {
+		return new this({
+			currentPageIndex: Number(response.headers.get("X-Pagination-Current-Page") ?? "1"),
+			itemsPerPage: Number(response.headers.get("X-Pagination-Per-Page") ?? "25"),
+			totalItemCount: Number(response.headers.get("X-Pagination-Total-Count") ?? "0")
+		});
+	}
+}
+
+/**
+ * Defines the options of a {@link Pagination} instance.
+ */
+export type PaginationOptions = Partial<{
+
+	/**
+	 * The one-based current page number.
+	 */
+	currentPageIndex: number;
+
+	/**
+	 * The number of items per page.
+	 */
+	itemsPerPage: number;
+
+	/**
+	 * The total number of items.
+	 */
+	totalItemCount: number;
+}>;

package/src/Client/Data/Sort.ts

@@ -1,21 +1,21 @@
 /**
- * Specifies the order of a sorted property.
+ * Specifies the order of a sort property.
  */
 export const SortOrder = Object.freeze({
 
 	/**
 	 * The sort is ascending.
 	 */
-	Ascending: "ASC",
+	Ascending: "Ascending",
 
 	/**
 	 * The sort is descending.
 	 */
-	Descending: "DESC"
+	Descending: "Descending"
 });
 
 /**
- * Specifies the order of a sorted property.
+ * Specifies the order of a sort property.
  */
 export type SortOrder = typeof SortOrder[keyof typeof SortOrder];
 
@@ -30,7 +30,7 @@ export type SortProperty = [string, SortOrder];
 export class Sort implements Iterable<SortProperty> {
 
 	/**
-	 * The list of sorted properties.
+	 * The list of sort properties.
 	 */
 	#properties: SortProperty[];
 
@@ -43,7 +43,14 @@ export class Sort implements Iterable<SortProperty> {
 	}
 
 	/**
-	 * The number of properties.
+	 * The list of sort properties.
+	 */
+	get keys(): string[] {
+		return this.#properties.map(item => item[0]);
+	}
+
+	/**
+	 * The number of properties in this sort.
 	 */
 	get length(): number {
 		return this.#properties.length;
@@ -73,33 +80,39 @@ export class Sort implements Iterable<SortProperty> {
 
 	/**
 	 * Returns a new iterator that allows iterating the entries of this sort.
-	 * @returns An iterator over the sorted properties.
+	 * @returns An iterator over the sort properties.
 	 */
-	*[Symbol.iterator](): Generator<SortProperty, void, void> {
-		for (const entry of this.#properties) yield entry;
+	[Symbol.iterator](): Iterator<SortProperty> {
+		return this.#properties[Symbol.iterator]();
 	}
 
 	/**
 	 * Appends the specified property to this sort.
 	 * @param property The property name.
 	 * @param order The sort order.
-	 * @returns This instance.
+	 * @throws `Error` when an item with the property name already exists.
 	 */
-	append(property: string, order: SortOrder): this {
-		this.delete(property);
+	add(property: string, order: SortOrder): void {
+		if (this.containsKey(property)) throw new Error("An item with the property name has already been added.");
 		this.#properties.push([property, order]);
-		return this;
 	}
 
 	/**
-	 * Gets the sorted property at the specified index.
+	 * Gets the sort property at the specified index.
 	 * @param index The position in this sort.
-	 * @returns The sorted property at the specified index, or `null` if it doesn't exist.
+	 * @returns The sort property at the specified index, or `null` if it doesn't exist.
 	 */
 	at(index: number): SortProperty|null {
 		return this.#properties.at(index) ?? null;
 	}
 
+	/**
+	 * Removes all properties from this sort.
+	 */
+	clear(): void {
+		this.#properties = [];
+	}
+
 	/**
 	 * Compares the specified objects, according to the current sort properties.
 	 * @param x The first object to compare.
@@ -117,6 +130,15 @@ export class Sort implements Iterable<SortProperty> {
 		return 0;
 	}
 
+	/**
+	 * Returns a value indicating whether the specified property exists in this sort.
+	 * @param property The property name.
+	 * @returns `true` if the specified property exists in this sort, otherwise `false`.
+	 */
+	containsKey(property: string): boolean {
+		return this.#properties.some(([key]) => key == property);
+	}
+
 	/**
 	 * Removes the specified property from this sort.
 	 * @param property The property name.
@@ -148,15 +170,6 @@ export class Sort implements Iterable<SortProperty> {
 		}
 	}
 
-	/**
-	 * Returns a value indicating whether the specified property exists in this sort.
-	 * @param property The property name.
-	 * @returns `true` if the specified property exists in this sort, otherwise `false`.
-	 */
-	has(property: string): boolean {
-		return this.#properties.some(([key]) => key == property);
-	}
-
 	/**
 	 * Gets the index of the specified property in the underlying list.
 	 * @param property The property name.
@@ -207,7 +220,8 @@ export class Sort implements Iterable<SortProperty> {
 			return this;
 		}
 
-		return this.append(property, order);
+		this.add(property, order);
+		return this;
 	}
 
 	/**
@@ -218,20 +232,11 @@ export class Sort implements Iterable<SortProperty> {
 		return this.toString();
 	}
 
-	/**
-	 * Converts this sort to an SQL clause.
-	 * @param escape A function used to escape the SQL identifiers.
-	 * @returns The SQL clause corresponding to this object.
-	 */
-	toSql(escape: (identifier: string) => string = id => id): string {
-		return this.#properties.map(([property, order]) => `${escape(property)} ${order}`).join(", ");
-	}
-
 	/**
 	 * Returns a string representation of this object.
 	 * @returns The string representation of this object.
 	 */
 	toString(): string {
-		return this.#properties.map(([property, order]) => `${order == SortOrder.Descending ? "-" : ""}${property}`).join();
+		return this.#properties.map(([property, order]) => `${order == SortOrder.Descending ? "-" : ""}${property}`).join(",");
 	}
 }

package/src/Client/Data/tsconfig.json

@@ -1,6 +1,6 @@
 {
 	"extends": "../../../tsconfig.json",
-	"include": ["*.ts"],
+	"include": ["**/*.ts"],
 	"compilerOptions": {
 		"composite": true,
 		"declaration": true,

package/src/Client/{Html/File.ts → FileExtensions.ts}

@@ -4,7 +4,7 @@ import {Duration} from "#Base/Duration.js";
  * Downloads the specified file.
  * @param file The file to be downloaded.
  */
-export function downloadFile(file: File): void {
+export function download(file: File): void {
 	const url = URL.createObjectURL(file);
 	const anchor = document.createElement("a");
 	anchor.download = file.name;
@@ -16,22 +16,12 @@ export function downloadFile(file: File): void {
 	URL.revokeObjectURL(url);
 }
 
-/**
- * Downloads the specified text content.
- * @param text The text content.
- * @param fileName The file name.
- * @param options The optional attributes for the file.
- */
-export function downloadString(text: string, fileName: string, options: FilePropertyBag = {}): void {
-	downloadFile(new File([text], fileName, options));
-}
-
 /**
  * Opens the specified file.
  * @param file The file to be opened.
  * @param options Value indicating whether to open the file in a new tab.
  */
-export function openFile(file: File, options: {newTab?: boolean} = {}): void {
+export function open(file: File, options: {newTab?: boolean} = {}): void {
 	const url = URL.createObjectURL(file);
 	if (!options.newTab) {
 		location.assign(url);
@@ -55,7 +45,7 @@ export function openFile(file: File, options: {newTab?: boolean} = {}): void {
  * Prints the specified file.
  * @param file The file to be printed.
  */
-export function printFile(file: File): void {
+export function print(file: File): void {
 	const url = URL.createObjectURL(file);
 	const frame = document.createElement("iframe");
 	frame.addEventListener("load", () => frame.contentWindow?.print());

package/src/Client/{Http → Net/Http}/HttpClient.ts

@@ -1,5 +1,6 @@
-import type {ILoadingIndicator} from "#Abstractions/ILoadingIndicator.js";
-import {HttpError} from "./HttpError.js";
+import {MediaType} from "../Mime/MediaType.js";
+import {HttpMethod} from "./HttpMethod.js";
+import {HttpRequestError} from "./HttpRequestError.js";
 
 /**
  * Performs HTTP requests.
@@ -9,7 +10,7 @@ export class HttpClient {
 	/**
 	 * The base URL of the remote service.
 	 */
-	readonly baseUrl: URL;
+	readonly baseAddress: URL;
 
 	/**
 	 * The function returning the component used as loading indicator.
@@ -22,8 +23,8 @@ export class HttpClient {
 	 */
 	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);
+		this.baseAddress = new URL(url.endsWith("/") ? url : `${url}/`);
+		this.#loadingIndicator = options.loadingIndicator ?? (() => document.body.querySelector("loading-indicator, .loading-indicator") as ILoadingIndicator|null);
 	}
 
 	/**
@@ -33,7 +34,7 @@ export class HttpClient {
 	 * @returns The server response.
 	 */
 	delete(url?: string|URL, options?: RequestInit): Promise<Response> {
-		return this.#fetch("DELETE", url, null, options);
+		return this.#fetch(HttpMethod.Delete, url, null, options);
 	}
 
 	/**
@@ -43,7 +44,7 @@ export class HttpClient {
 	 * @returns The server response.
 	 */
 	get(url?: string|URL, options?: RequestInit): Promise<Response> {
-		return this.#fetch("GET", url, null, options);
+		return this.#fetch(HttpMethod.Get, url, null, options);
 	}
 
 	/**
@@ -54,7 +55,7 @@ export class HttpClient {
 	 * @returns The server response.
 	 */
 	patch(url?: string|URL, body?: unknown, options?: RequestInit): Promise<Response> {
-		return this.#fetch("PATCH", url, body, options);
+		return this.#fetch(HttpMethod.Patch, url, body, options);
 	}
 
 	/**
@@ -65,7 +66,7 @@ export class HttpClient {
 	 * @returns The server response.
 	 */
 	post(url?: string|URL, body?: unknown, options?: RequestInit): Promise<Response> {
-		return this.#fetch("POST", url, body, options);
+		return this.#fetch(HttpMethod.Post, url, body, options);
 	}
 
 	/**
@@ -76,7 +77,7 @@ export class HttpClient {
 	 * @returns The server response.
 	 */
 	put(url?: string|URL, body?: unknown, options?: RequestInit): Promise<Response> {
-		return this.#fetch("PUT", url, body, options);
+		return this.#fetch(HttpMethod.Put, url, body, options);
 	}
 
 	/**
@@ -89,19 +90,19 @@ export class HttpClient {
 	 */
 	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 (!headers.has("Accept")) headers.set("Accept", MediaType.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");
+			if (!headers.has("Content-Type")) headers.set("Content-Type", MediaType.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 request = new Request(new URL(url, this.baseAddress), {...options, method, headers, body} as RequestInit);
 			const response = await fetch(request);
-			if (!response.ok) throw new HttpError(response);
+			if (!response.ok) throw new HttpRequestError(response);
 			return response;
 		}
 		finally {
@@ -125,3 +126,20 @@ export type HttpClientOptions = Partial<{
 	 */
 	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;
+}