@cedx/base 0.4.1 → 0.6.0

package/lib/UI/MenuActivator.js

@@ -1,5 +1,5 @@
 /**
- * A component that activates the items of a menu based on the current document URL.
+ * A component that activates the items of a menu, based on the current document URL.
  */
 export class MenuActivator extends HTMLElement {
     /**
@@ -12,7 +12,7 @@ export class MenuActivator extends HTMLElement {
      * Method invoked when this component is connected.
      */
     connectedCallback() {
-        for (const anchor of this.firstElementChild.getElementsByTagName("a"))
+        for (const anchor of this.querySelectorAll("a"))
             if (anchor.href != location.href)
                 anchor.classList.remove("active");
             else {

package/lib/UI/ThemeDropdown.d.ts

@@ -1,3 +1,4 @@
+import { AppTheme } from "#Html/AppTheme.js";
 /**
  * A dropdown menu for switching the application theme.
  */
@@ -7,6 +8,11 @@ export declare class ThemeDropdown extends HTMLElement {
      * Creates a new theme dropdown.
      */
     constructor();
+    /**
+     * The current application theme.
+     */
+    get theme(): AppTheme;
+    set theme(value: AppTheme);
     /**
      * Method invoked when this component is connected.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"ThemeDropdown.d.ts","sourceRoot":"","sources":["../../src/Client/UI/ThemeDropdown.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,qBAAa,aAAc,SAAQ,WAAW;;IAsB7C;;OAEG;;IAeH;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAKzB;;OAEG;IACH,oBAAoB,IAAI,IAAI;IAI5B;;OAEG;IACH,WAAW,IAAI,IAAI;CA2BnB;AAED;;GAEG;AACH,OAAO,CAAC,MAAM,CAAC;IAEd;;OAEG;IACH,UAAU,qBAAqB;QAC9B,gBAAgB,EAAE,aAAa,CAAC;KAChC;CACD"}
+{"version":3,"file":"ThemeDropdown.d.ts","sourceRoot":"","sources":["../../src/Client/UI/ThemeDropdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAU,MAAM,mBAAmB,CAAC;AAEpD;;GAEG;AACH,qBAAa,aAAc,SAAQ,WAAW;;IAiB7C;;OAEG;;IAeH;;OAEG;IACH,IAAI,KAAK,IAAI,QAAQ,CAEpB;IACD,IAAI,KAAK,CAAC,KAAK,EAAE,QAAQ,EAGxB;IAED;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAKzB;;OAEG;IACH,oBAAoB,IAAI,IAAI;IAI5B;;OAEG;IACH,WAAW,IAAI,IAAI;CAsBnB;AAED;;GAEG;AACH,OAAO,CAAC,MAAM,CAAC;IAEd;;OAEG;IACH,UAAU,qBAAqB;QAC9B,gBAAgB,EAAE,aAAa,CAAC;KAChC;CACD"}

package/lib/UI/ThemeDropdown.js

@@ -7,10 +7,6 @@ export class ThemeDropdown extends HTMLElement {
      * The media query used to check the application theme.
      */
     #mediaQuery = matchMedia("(prefers-color-scheme: dark)");
-    /**
-     * The root element.
-     */
-    #root = this.firstElementChild;
     /**
      * The key of the storage entry providing the saved theme mode.
      */
@@ -26,7 +22,7 @@ export class ThemeDropdown extends HTMLElement {
         super();
         const theme = localStorage.getItem(this.#storageKey);
         this.#theme = Object.values(AppTheme).includes(theme) ? theme : AppTheme.System;
-        for (const button of this.#root.querySelectorAll("button"))
+        for (const button of this.querySelectorAll("button"))
             button.addEventListener("click", this.#setTheme.bind(this));
     }
     /**
@@ -35,6 +31,16 @@ export class ThemeDropdown extends HTMLElement {
     static {
         customElements.define("theme-dropdown", this);
     }
+    /**
+     * The current application theme.
+     */
+    get theme() {
+        return this.#theme;
+    }
+    set theme(value) {
+        localStorage.setItem(this.#storageKey, this.#theme = value);
+        this.#applyTheme();
+    }
     /**
      * Method invoked when this component is connected.
      */
@@ -60,11 +66,8 @@ export class ThemeDropdown extends HTMLElement {
     #applyTheme() {
         const theme = this.#theme == AppTheme.System ? (this.#mediaQuery.matches ? AppTheme.Dark : AppTheme.Light) : this.#theme;
         document.documentElement.dataset.bsTheme = theme.toLowerCase();
-        this.#root.querySelector(".dropdown-toggle > .icon").textContent = getIcon(this.#theme);
-        const checkIcon = this.#root.querySelector(".dropdown-item > .icon");
-        checkIcon.remove();
-        const activeButton = this.#root.querySelector(`button[data-theme="${this.#theme}"]`);
-        activeButton.appendChild(checkIcon);
+        this.querySelector(".dropdown-toggle > .icon").textContent = getIcon(this.#theme);
+        this.querySelector(`button[data-theme="${this.#theme}"]`).appendChild(this.querySelector(".dropdown-item > .icon"));
     }
     /**
      * Changes the current theme.
@@ -72,7 +75,6 @@ export class ThemeDropdown extends HTMLElement {
      */
     #setTheme(event) {
         const button = event.target.closest("button");
-        localStorage.setItem(this.#storageKey, this.#theme = button.dataset.theme);
-        this.#applyTheme();
+        this.theme = button.dataset.theme;
     }
 }

package/package.json

@@ -7,7 +7,7 @@
 	"name": "@cedx/base",
 	"repository": "cedx/base",
 	"type": "module",
-	"version": "0.4.1",
+	"version": "0.6.0",
 	"devDependencies": {
 		"@playwright/browser-chromium": "^1.54.2",
 		"@types/bootstrap": "^5.2.10",
@@ -51,7 +51,7 @@
 	],
 	"peerDependencies": {
 		"bootstrap": ">=5.3.0",
-		"tslib": ">=2.8.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,90 @@
+/**
+ * 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 = Math.max(1, options.currentPageIndex ?? 1);
+		this.itemsPerPage = Math.max(1, Math.min(1000, options.itemsPerPage ?? 25));
+		this.totalItemCount = Math.max(0, options.totalItemCount ?? 0);
+	}
+
+	/**
+	 * Value indicating whether a next page exists.
+	 */
+	get hasNextPage(): boolean {
+		return this.currentPageIndex < this.totalItemCount;
+	}
+
+	/**
+	 * Value indicating whether a previous page exists.
+	 */
+	get hasPreviousPage(): boolean {
+		return this.currentPageIndex > 1;
+	}
+
+	/**
+	 * The one-based last page number.
+	 */
+	get lastPageIndex(): number {
+		return Math.ceil(this.totalItemCount / this.itemsPerPage);
+	}
+
+	/**
+	 * 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()});
+	}
+
+	/**
+	 * 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<Pick<Pagination, "currentPageIndex"|"itemsPerPage"|"totalItemCount">>;

package/src/Client/Data/Sort.ts

@@ -0,0 +1,237 @@
+/**
+ * Specifies the order of a sorted property.
+ */
+export const SortOrder = Object.freeze({
+
+	/**
+	 * The sort is ascending.
+	 */
+	Ascending: "ASC",
+
+	/**
+	 * The sort is descending.
+	 */
+	Descending: "DESC"
+});
+
+/**
+ * Specifies the order of a sorted property.
+ */
+export type SortOrder = typeof SortOrder[keyof typeof SortOrder];
+
+/**
+ * Holds the name of a property and the order to sort by.
+ */
+export type SortProperty = [string, SortOrder];
+
+/**
+ * Represents information relevant to the sorting of data items.
+ */
+export class Sort implements Iterable<SortProperty> {
+
+	/**
+	 * The list of sorted properties.
+	 */
+	#properties: SortProperty[];
+
+	/**
+	 * Creates new sort.
+	 * @param properties The list of properties to be sorted.
+	 */
+	constructor(properties: SortProperty[] = []) {
+		this.#properties = properties;
+	}
+
+	/**
+	 * The number of properties.
+	 */
+	get length(): number {
+		return this.#properties.length;
+	}
+
+	/**
+	 * Creates a new sort from the specified property and order.
+	 * @param property The property name.
+	 * @param order The sort order.
+	 * @returns The sort corresponding to the property and order.
+	 */
+	static of(property: string, order: SortOrder = SortOrder.Ascending): Sort {
+		return new this([[property, order]]);
+	}
+
+	/**
+	 * Creates a new sort from the specified string.
+	 * @param value A string representing a sort.
+	 * @returns The sort corresponding to the specified string.
+	 */
+	static parse(value: string): Sort {
+		return new this((value ? value.split(",") : []).map(item => {
+			const order = item.startsWith("-") ? SortOrder.Descending : SortOrder.Ascending;
+			return [order == SortOrder.Ascending ? item : item.slice(1), order];
+		}));
+	}
+
+	/**
+	 * Returns a new iterator that allows iterating the entries of this sort.
+	 * @returns An iterator over the sorted properties.
+	 */
+	*[Symbol.iterator](): Generator<SortProperty, void, void> {
+		for (const entry of this.#properties) yield entry;
+	}
+
+	/**
+	 * Appends the specified property to this sort.
+	 * @param property The property name.
+	 * @param order The sort order.
+	 * @returns This instance.
+	 */
+	append(property: string, order: SortOrder): this {
+		this.delete(property);
+		this.#properties.push([property, order]);
+		return this;
+	}
+
+	/**
+	 * Gets the sorted 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.
+	 */
+	at(index: number): SortProperty|null {
+		return this.#properties.at(index) ?? null;
+	}
+
+	/**
+	 * Compares the specified objects, according to the current sort properties.
+	 * @param x The first object to compare.
+	 * @param y The second object to compare.
+	 * @returns A value indicating the relationship between the two objects.
+	 */
+	compare(x: object, y: object): number {
+		for (const [property, order] of this.#properties) {
+			const xAttr = Reflect.get(x, property); // eslint-disable-line @typescript-eslint/no-unsafe-assignment
+			const yAttr = Reflect.get(y, property); // eslint-disable-line @typescript-eslint/no-unsafe-assignment
+			const value = xAttr > yAttr ? 1 : (xAttr < yAttr ? -1 : 0);
+			if (value) return order == SortOrder.Ascending ? value : -value;
+		}
+
+		return 0;
+	}
+
+	/**
+	 * Removes the specified property from this sort.
+	 * @param property The property name.
+	 */
+	delete(property: string): void {
+		this.#properties = this.#properties.filter(([key]) => key != property);
+	}
+
+	/**
+	 * Gets the order associated with the specified property.
+	 * @param property The property name.
+	 * @returns The order associated with the specified property, or `null` if the property doesn't exist.
+	 */
+	get(property: string): SortOrder|null {
+		for (const [key, order] of this.#properties) if (key == property) return order;
+		return null;
+	}
+
+	/**
+	 * Gets the icon corresponding to the specified property.
+	 * @param property The property name.
+	 * @returns The icon corresponding to the specified property.
+	 */
+	getIcon(property: string): string {
+		switch (this.get(property)) {
+			case SortOrder.Ascending: return "arrow_upward";
+			case SortOrder.Descending: return "arrow_downward";
+			default: return "swap_vert";
+		}
+	}
+
+	/**
+	 * 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.
+	 * @returns The index of the specified property, or `-1` if the property is not found.
+	 */
+	indexOf(property: string): number {
+		for (const [index, [key]] of this.#properties.entries()) if (key == property) return index;
+		return -1;
+	}
+
+	/**
+	 * Prepends the specified property to this sort.
+	 * @param property The property name.
+	 * @param order The sort order.
+	 * @returns This instance.
+	 */
+	prepend(property: string, order: SortOrder): this {
+		this.delete(property);
+		this.#properties.unshift([property, order]);
+		return this;
+	}
+
+	/**
+	 * Returns a value indicating whether the current sort satisfies the specified conditions.
+	 * @param conditions The conditions to satisfy.
+	 * @returns `true` if the current sort satisfies the specified conditions, otherwise `false`.
+	 */
+	satisfies(conditions: Partial<{min: number, max: number, properties: string[]}> = {}): boolean {
+		const min = conditions.min ?? -1;
+		if (min >= 0) return this.length >= min;
+
+		const max = conditions.max ?? -1;
+		if (max >= 0) return this.length <= max;
+
+		const properties = conditions.properties ?? [];
+		return properties.length ? this.#properties.every(([key]) => properties.includes(key)) : true;
+	}
+
+	/**
+	 * Sets the order of the specified property.
+	 * @param property The property name.
+	 * @param order The sort order.
+	 * @returns This instance.
+	 */
+	set(property: string, order: SortOrder): this {
+		for (const [index, [key]] of this.#properties.entries()) if (key == property) {
+			this.#properties[index] = [key, order];
+			return this;
+		}
+
+		return this.append(property, order);
+	}
+
+	/**
+	 * Returns a JSON representation of this object.
+	 * @returns The JSON representation of this object.
+	 */
+	toJSON(): string {
+		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();
+	}
+}

package/src/Client/Data/tsconfig.json

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

package/src/Client/DependencyInjection/Container.ts

@@ -30,7 +30,7 @@ export class Container {
 	 */
 	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)!());
+			if (this.#factories.has(id)) this.set(id, this.#factories.get(id)!.call(this));
 			else if (typeof id == "function") this.set(id, Reflect.construct(id, []));
 			else throw Error("There is no factory registered with the specified identifier.");
 

package/src/Client/Html/Context.ts

@@ -34,7 +34,7 @@ export type Context = typeof Context[keyof typeof Context];
  * @param context The context.
  * @returns The icon corresponding to the specified context.
  */
-export function contextIcon(context: Context): string {
+export function getIcon(context: Context): string {
 	switch (context) {
 		case Context.Danger: return "error";
 		case Context.Success: return "check_circle";

package/src/Client/UI/Component.ts

@@ -0,0 +1,34 @@
+import {LitElement, type CSSResultGroup} from "lit";
+
+/**
+ * The optional base class for UI components. Alternatively, components may extend {@link LitElement} directly.
+ */
+export abstract class Component extends LitElement {
+
+	/**
+	 * The component styles.
+	 */
+	static override styles: CSSResultGroup = [document.adoptedStyleSheets];
+
+	/**
+	 * Value indicating whether this component uses a shadow root.
+	 */
+	readonly #useShadowRoot: boolean;
+
+	/**
+	 * Creates a new component.
+	 * @param options Value indicating whether this component uses a shadow root.
+	 */
+	constructor(options: {shadowRoot?: boolean} = {}) {
+		super();
+		this.#useShadowRoot = options.shadowRoot ?? 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.#useShadowRoot ? super.createRenderRoot() : this;
+	}
+}

package/src/Client/UI/MenuActivator.ts

@@ -1,5 +1,5 @@
 /**
- * A component that activates the items of a menu based on the current document URL.
+ * A component that activates the items of a menu, based on the current document URL.
  */
 export class MenuActivator extends HTMLElement {
 
@@ -14,7 +14,7 @@ export class MenuActivator extends HTMLElement {
 	 * Method invoked when this component is connected.
 	 */
 	connectedCallback(): void {
-		for (const anchor of this.firstElementChild!.getElementsByTagName("a"))
+		for (const anchor of this.querySelectorAll("a"))
 			if (anchor.href != location.href) anchor.classList.remove("active");
 			else {
 				anchor.classList.add("active");

package/src/Client/UI/ThemeDropdown.ts

@@ -10,11 +10,6 @@ export class ThemeDropdown extends HTMLElement {
 	 */
 	readonly #mediaQuery = matchMedia("(prefers-color-scheme: dark)");
 
-	/**
-	 * The root element.
-	 */
-	readonly #root = this.firstElementChild!;
-
 	/**
 	 * The key of the storage entry providing the saved theme mode.
 	 */
@@ -32,7 +27,7 @@ export class ThemeDropdown extends HTMLElement {
 		super();
 		const theme = localStorage.getItem(this.#storageKey) as AppTheme;
 		this.#theme = Object.values(AppTheme).includes(theme) ? theme : AppTheme.System;
-		for (const button of this.#root.querySelectorAll("button")) button.addEventListener("click", this.#setTheme.bind(this));
+		for (const button of this.querySelectorAll("button")) button.addEventListener("click", this.#setTheme.bind(this));
 	}
 
 	/**
@@ -42,6 +37,17 @@ export class ThemeDropdown extends HTMLElement {
 		customElements.define("theme-dropdown", this);
 	}
 
+	/**
+	 * The current application theme.
+	 */
+	get theme(): AppTheme {
+		return this.#theme;
+	}
+	set theme(value: AppTheme) {
+		localStorage.setItem(this.#storageKey, this.#theme = value);
+		this.#applyTheme();
+	}
+
 	/**
 	 * Method invoked when this component is connected.
 	 */
@@ -70,12 +76,8 @@ export class ThemeDropdown extends HTMLElement {
 	#applyTheme(): void {
 		const theme = this.#theme == AppTheme.System ? (this.#mediaQuery.matches ? AppTheme.Dark : AppTheme.Light) : this.#theme;
 		document.documentElement.dataset.bsTheme = theme.toLowerCase();
-		this.#root.querySelector(".dropdown-toggle > .icon")!.textContent = getIcon(this.#theme);
-
-		const checkIcon = this.#root.querySelector(".dropdown-item > .icon")!;
-		checkIcon.remove();
-		const activeButton = this.#root.querySelector(`button[data-theme="${this.#theme}"]`)!
-		activeButton.appendChild(checkIcon);
+		this.querySelector(".dropdown-toggle > .icon")!.textContent = getIcon(this.#theme);
+		this.querySelector(`button[data-theme="${this.#theme}"]`)!.appendChild(this.querySelector(".dropdown-item > .icon")!);
 	}
 
 	/**
@@ -84,8 +86,7 @@ export class ThemeDropdown extends HTMLElement {
 	 */
 	#setTheme(event: Event): void {
 		const button = (event.target as HTMLElement).closest("button")!;
-		localStorage.setItem(this.#storageKey, this.#theme = button.dataset.theme as AppTheme);
-		this.#applyTheme();
+		this.theme = button.dataset.theme as AppTheme;
 	}
 }
 

package/src/Client/UI/tsconfig.json

@@ -5,12 +5,10 @@
 		"composite": true,
 		"declaration": true,
 		"declarationMap": true,
-		"importHelpers": true,
 		"noEmit": false,
 		"outDir": "../../../lib/UI",
 		"rootDir": ".",
-		"tsBuildInfoFile": "../../../var/UI.tsbuildinfo",
-		"useDefineForClassFields": false
+		"tsBuildInfoFile": "../../../var/UI.tsbuildinfo"
 	},
 	"references": [
 		{"path": "../Abstractions/tsconfig.json"},

package/src/Client/tsconfig.json

@@ -3,6 +3,7 @@
 	"references": [
 		{"path": "Abstractions/tsconfig.json"},
 		{"path": "Base/tsconfig.json"},
+		{"path": "Data/tsconfig.json"},
 		{"path": "DependencyInjection/tsconfig.json"},
 		{"path": "Html/tsconfig.json"},
 		{"path": "Http/tsconfig.json"},