@cedx/ui 0.1.0

package/src/Client/Components/DialogBox.ts

@@ -0,0 +1,344 @@
+import {Modal} from "bootstrap";
+import {type Context, cssClass as contextCssClass, icon as contextIcon} from "../Context.js";
+import {DialogResult} from "../DialogResult.js";
+import {html} from "../Tags.js";
+import {Variant, cssClass as variantCssClass} from "../Variant.js";
+
+/**
+ * Represents a dialog box button.
+ */
+export interface IDialogButton {
+
+	/**
+	 * The button icon.
+	 */
+	icon?: string;
+
+	/**
+	 * The button label.
+	 */
+	label?: string;
+
+	/**
+	 * The button value.
+	 */
+	value?: string;
+
+	/**
+	 * A tone variant.
+	 */
+	variant?: Variant;
+}
+
+/**
+ * Represents a message to display in a dialog box.
+ */
+export interface IDialogMessage {
+
+	/**
+	 * The child content displayed in the body.
+	 */
+	body: DocumentFragment;
+
+	/**
+	 * The title displayed in the header.
+	 */
+	caption: string;
+
+	/**
+	 * The child content displayed in the footer.
+	 */
+	footer?: DocumentFragment;
+}
+
+/**
+ * Displays a dialog box, which presents a message to the user.
+ */
+export class DialogBox extends HTMLElement {
+
+	/**
+	 * The list of observed attributes.
+	 */
+	static readonly observedAttributes = ["caption", "centered", "fade", "modal", "scrollable"];
+
+	/**
+	 * The underlying Bootstrap modal.
+	 */
+	#modal!: Modal;
+
+	/**
+	 * The function invoked to resolve the dialog result.
+	 */
+	#resolve!: (value: string) => void;
+
+	/**
+	 * The promise providing the dialog result.
+	 */
+	#result: string = DialogResult.None;
+
+	/**
+	 * Creates a new dialog box.
+	 */
+	constructor() {
+		super();
+		this.firstElementChild!.addEventListener("hide.bs.modal", () => this.#resolve(this.#result));
+		this.querySelector(".btn-close")!.addEventListener("click", this.#close);
+		for (const button of this.querySelectorAll(".modal-footer button")) button.addEventListener("click", this.#close);
+	}
+
+	/**
+	 * Registers the component.
+	 */
+	static {
+		customElements.define("dialog-box", this);
+	}
+
+	/**
+	 * The child content displayed in the body.
+	 */
+	set body(value: DocumentFragment) { // eslint-disable-line accessor-pairs
+		this.querySelector(".modal-body")!.replaceChildren(...value.childNodes);
+	}
+
+	/**
+	 * The title displayed in the header.
+	 */
+	get caption(): string {
+		return (this.getAttribute("caption") ?? "").trim();
+	}
+	set caption(value: string) {
+		this.setAttribute("caption", value);
+	}
+
+	/**
+	 * Value indicating whether to vertically center this dialog box.
+	 */
+	get centered(): boolean {
+		return this.hasAttribute("centered");
+	}
+	set centered(value: boolean) {
+		this.toggleAttribute("centered", value);
+	}
+
+	/**
+	 * Value indicating whether to apply a transition.
+	 */
+	get fade(): boolean {
+		return this.hasAttribute("fade");
+	}
+	set fade(value: boolean) {
+		this.toggleAttribute("fade", value);
+	}
+
+	/**
+	 * The child content displayed in the footer.
+	 */
+	set footer(value: DocumentFragment) { // eslint-disable-line accessor-pairs
+		const footer = this.querySelector<HTMLElement>(".modal-footer")!;
+		footer.hidden = !value.hasChildNodes();
+		footer.replaceChildren(...value.childNodes);
+	}
+
+	/**
+	 * Value indicating whether to this dialog box will not close when clicking outside of it.
+	 */
+	get modal(): boolean {
+		return this.hasAttribute("modal");
+	}
+	set modal(value: boolean) {
+		this.toggleAttribute("modal", value);
+	}
+
+	/**
+	 * Value indicating whether to initially show this component.
+	 */
+	get open(): boolean {
+		return this.hasAttribute("open");
+	}
+	set open(value: boolean) {
+		this.toggleAttribute("open", value);
+	}
+
+	/**
+	 * The dialog result.
+	 */
+	get result(): string {
+		return this.#result;
+	}
+
+	/**
+	 * Value indicating whether the body is scrollable.
+	 */
+	get scrollable(): boolean {
+		return this.hasAttribute("scrollable");
+	}
+	set scrollable(value: boolean) {
+		this.toggleAttribute("scrollable", 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 "caption": this.#updateCaption(newValue ?? ""); break;
+			case "centered": this.#updateCentered(newValue != null); break;
+			case "fade": this.#updateFade(newValue != null); break;
+			case "modal": this.#updateModal(newValue != null); break;
+			case "scrollable": this.#updateScrollable(newValue != null); break;
+			// No default
+		}
+	}
+
+	/**
+	 * Shows an alert message with an "OK" button by default.
+	 * @param context The contextual modifier.
+	 * @param caption The title displayed in the header.
+	 * @param message The child content displayed in the body.
+	 * @param buttons The buttons displayed in the footer.
+	 * @returns The dialog result.
+	 */
+	alert(context: Context, caption: string, message: DocumentFragment, buttons: IDialogButton[] = []): Promise<string> {
+		return this.show({
+			caption,
+			body: html`
+				<div class="d-flex gap-2">
+					<i class="icon icon-fill fs-1 text-${contextCssClass(context)}"> ${contextIcon(context)}</i>
+					<div class="flex-grow-1">${message}</div>
+				</div>
+			`,
+			footer: html`
+				${(buttons.length ? buttons : [{label: "OK", value: DialogResult.OK, variant: Variant.Primary}]).map(button => html`
+					<button class="btn btn-${variantCssClass(button.variant ?? Variant.Primary)}" type="button" value="${button.value ?? DialogResult.None}">
+						${button.icon ? html`<i class="icon ${button.label ? "me-1" : ""}">${button.icon}</i>` : ""}
+						${button.label}
+					</button>
+				`)}
+			`
+		});
+	}
+
+	/**
+	 * Closes this dialog box.
+	 * @param result The dialog result.
+	 */
+	close(result: string = DialogResult.None): void {
+		this.#result = result;
+		this.#modal.hide();
+	}
+
+	/**
+	 * Shows a confirmation message with two buttons, "OK" and "Cancel".
+	 * @param context The contextual modifier.
+	 * @param caption The title displayed in the header.
+	 * @param message The child content displayed in the body.
+	 * @returns The dialog result.
+	 */
+	confirm(context: Context, caption: string, message: DocumentFragment): Promise<string> {
+		return this.alert(context, caption, message, [
+			{label: "OK", value: DialogResult.OK, variant: Variant.Primary},
+			{label: "Annuler", value: DialogResult.Cancel, variant: Variant.Secondary}
+		]);
+	}
+
+	/**
+	 * Method invoked when this component is connected.
+	 */
+	connectedCallback(): void {
+		this.#modal = new Modal(this.firstElementChild!);
+		if (this.open) void this.show();
+	}
+
+	/**
+	 * Method invoked when this component is disconnected.
+	 */
+	disconnectedCallback(): void {
+		this.#modal.dispose();
+	}
+
+	/**
+	 * Shows a message.
+	 * @param message The message to show.
+	 * @returns The dialog result.
+	 */
+	show(message: IDialogMessage|null = null): Promise<string> {
+		if (message) {
+			const footer = message.footer ?? document.createDocumentFragment();
+			for (const button of footer.querySelectorAll("button")) button.addEventListener("click", this.#close);
+			this.body = message.body;
+			this.caption = message.caption;
+			this.footer = footer;
+		}
+
+		const {promise, resolve} = Promise.withResolvers<string>();
+		this.#resolve = resolve;
+		this.#result = DialogResult.None;
+		this.#modal.show();
+		return promise;
+	}
+
+	/**
+	 * Closes this dialog box.
+	 * @param event The dispatched event.
+	 */
+	readonly #close: (event: Event) => void = event => {
+		event.preventDefault();
+		this.close((event.currentTarget as HTMLButtonElement).value);
+	};
+
+	/**
+	 * Updates the title displayed in the header.
+	 * @param value The new value.
+	 */
+	#updateCaption(value: string): void {
+		this.querySelector(".modal-title")!.textContent = value.trim();
+	}
+
+	/**
+	 * Updates the value indicating whether to vertically center this dialog box.
+	 * @param value The new value.
+	 */
+	#updateCentered(value: boolean): void {
+		this.querySelector(".modal-dialog")!.classList.toggle("modal-dialog-centered", value);
+	}
+
+	/**
+	 * Updates the value indicating whether to apply a transition.
+	 * @param value The new value.
+	 */
+	#updateFade(value: boolean): void {
+		this.firstElementChild!.classList.toggle("fade", value);
+	}
+
+	/**
+	 * Updates the value indicating whether to this dialog box will not close when clicking outside of it.
+	 * @param value The new value.
+	 */
+	#updateModal(value: boolean): void {
+		(this.firstElementChild! as HTMLElement).dataset.bsBackdrop = value ? "static" : "true";
+	}
+
+	/**
+	 * Updates the value indicating whether the body is scrollable.
+	 * @param value The new value.
+	 */
+	#updateScrollable(value: boolean): void {
+		this.querySelector(".modal-dialog")!.classList.toggle("modal-dialog-scrollable", value);
+	}
+}
+
+/**
+ * Declaration merging.
+ */
+declare global {
+
+	/**
+	 * The map of HTML tag names.
+	 */
+	interface HTMLElementTagNameMap {
+		"dialog-box": DialogBox;
+	}
+}

package/src/Client/Components/FullScreenToggler.ts

@@ -0,0 +1,122 @@
+/**
+ * A component for toggling an element to full-screen.
+ */
+export class FullScreenToggler extends HTMLElement {
+
+	/**
+	 * The abort controller used to remove the event listeners.
+	 */
+	#abortController: AbortController|null = null;
+
+	/**
+	 * The target element.
+	 */
+	#element: Element = document.body;
+
+	/**
+	 * The handle to the underlying platform wake lock.
+	 */
+	#sentinel: WakeLockSentinel|null = null;
+
+	/**
+	 * Registers the component.
+	 */
+	static {
+		customElements.define("fullscreen-toggler", this);
+	}
+
+	/**
+	 * The CSS selector specifying the target element.
+	 */
+	get target(): string {
+		const value = this.getAttribute("target") ?? "";
+		return value.trim() || "body";
+	}
+	set target(value: string) {
+		this.setAttribute("target", value);
+	}
+
+	/**
+	 * Value indicating whether to prevent the device screen from dimming or locking when in full-screen mode.
+	 */
+	get wakeLock(): boolean {
+		return this.hasAttribute("wakeLock");
+	}
+	set wakeLock(value: boolean) {
+		this.toggleAttribute("wakeLock", value);
+	}
+
+	/**
+	 * Method invoked when this component is connected.
+	 */
+	connectedCallback(): void {
+		this.#abortController = new AbortController;
+		document.addEventListener("visibilitychange", () => this.#onVisibilityChanged(), {signal: this.#abortController.signal});
+		this.#element = document.querySelector(this.target) ?? document.body;
+		this.#element.addEventListener("fullscreenchange", () => this.#onFullScreenChanged(), {signal: this.#abortController.signal});
+	}
+
+	/**
+	 * Method invoked when this component is disconnected.
+	 */
+	disconnectedCallback(): void {
+		this.#abortController?.abort();
+	}
+
+	/**
+	 * Toggles the full-screen mode of the associated element.
+	 * @param event The dispatched event.
+	 * @returns Completes when the full-screen mode has been toggled.
+	 */
+	async toggleFullScreen(event?: Event): Promise<void> {
+		event?.preventDefault();
+		if (document.fullscreenElement) await document.exitFullscreen();
+		else await this.#element.requestFullscreen();
+	}
+
+	/**
+	 * Acquires a new wake lock.
+	 * @returns Completes when the wake lock has been acquired.
+	 */
+	async #acquireWakeLock(): Promise<void> {
+		if (this.wakeLock && (!this.#sentinel || this.#sentinel.released)) this.#sentinel = await navigator.wakeLock.request();
+	}
+
+	/**
+	 * Acquires or releases the wake lock when the document enters or exits the full-screen mode.
+	 * @param event The dispatched event.
+	 */
+	#onFullScreenChanged(): void {
+		if (document.fullscreenElement) void this.#acquireWakeLock();
+		else void this.#releaseWakeLock();
+	}
+
+	/**
+	 * Eventually acquires a new wake lock when the document visibility has changed.
+	 * @param event The dispatched event.
+	 */
+	#onVisibilityChanged(): void {
+		if (document.fullscreenElement && !document.hidden) void this.#acquireWakeLock();
+	}
+
+	/**
+	 * Releases the acquired wake lock.
+	 * @returns Completes when the wake lock has been released.
+	 */
+	async #releaseWakeLock(): Promise<void> {
+		if (this.#sentinel && !this.#sentinel.released) await this.#sentinel.release();
+	}
+}
+
+/**
+ * Declaration merging.
+ */
+declare global {
+
+	/**
+	 * The map of HTML tag names.
+	 */
+	interface HTMLElementTagNameMap {
+		"fullscreen-toggler": FullScreenToggler;
+	}
+}

package/src/Client/Components/KeyboardAccelerator.ts

@@ -0,0 +1,97 @@
+import {KeyboardModifiers} from "../KeyboardModifiers.js";
+
+/**
+ * Associates a shortcut key with its child content.
+ */
+export class KeyboardAccelerator extends HTMLElement {
+
+	/**
+	 * The mapping between the modifier names and their values.
+	 */
+	static readonly #modifiers = new Map(Object.entries(KeyboardModifiers).filter(([key]) => key != "None"));
+
+	/**
+	 * The abort controller used to remove the event listeners.
+	 */
+	#abortController: AbortController|null = null;
+
+	/**
+	 * Registers the component.
+	 */
+	static {
+		customElements.define("keyboard-accelerator", this);
+	}
+
+	/**
+	 * Identifies the key for the keyboard accelerator.
+	 */
+	get key(): string {
+		return (this.getAttribute("key") ?? "").trim();
+	}
+	set key(value: string) {
+		this.setAttribute("key", value);
+	}
+
+	/**
+	 * Identifies the modifiers for the keyboard accelerator.
+	 */
+	get modifiers(): number {
+		return (this.getAttribute("modifiers") ?? "").split(",")
+			.map(value => value.trim())
+			.reduce<number>((modifiers, value) => modifiers | (KeyboardAccelerator.#modifiers.get(value) ?? 0), KeyboardModifiers.None);
+	}
+	set modifiers(value: number) {
+		this.setAttribute("modifiers", !value ? "None" : KeyboardAccelerator.#modifiers.entries()
+			.filter(([, flag]) => (value & flag) != 0)
+			.map(([key]) => key)
+			.toArray().join(", "));
+	}
+
+	/**
+	 * Method invoked when this component is connected.
+	 */
+	connectedCallback(): void {
+		this.#abortController = new AbortController;
+		addEventListener("keyup", event => this.#activateChildContent(event), {signal: this.#abortController.signal});
+	}
+
+	/**
+	 * Method invoked when this component is disconnected.
+	 */
+	disconnectedCallback(): void {
+		this.#abortController?.abort();
+	}
+
+	/**
+	 * Activates the child content when the specified keyboard event designates the same key and modifiers as this keyboard accelerator.
+	 * @param event The dispatched event.
+	 */
+	#activateChildContent(event: KeyboardEvent): void {
+		if (event.key != this.key) return;
+
+		const {activeElement} = document;
+		if (activeElement instanceof HTMLInputElement || activeElement instanceof HTMLTextAreaElement) return;
+
+		const {modifiers} = this;
+		if (!(modifiers & KeyboardModifiers.Ctrl) && event.ctrlKey) return;
+		if (!(modifiers & KeyboardModifiers.Shift) && event.shiftKey) return;
+		if (!(modifiers & KeyboardModifiers.Alt) && event.altKey) return;
+		if (!(modifiers & KeyboardModifiers.Meta) && event.metaKey) return;
+
+		event.preventDefault();
+		(this.firstElementChild as HTMLElement|null)?.click();
+	}
+}
+
+/**
+ * Declaration merging.
+ */
+declare global {
+
+	/**
+	 * The map of HTML tag names.
+	 */
+	interface HTMLElementTagNameMap {
+		"keyboard-accelerator": KeyboardAccelerator;
+	}
+}

package/src/Client/Components/LoadingIndicator.ts

@@ -0,0 +1,113 @@
+/**
+ * A component that shows up when an HTTP request starts, and hides when all concurrent HTTP requests are completed.
+ */
+export class LoadingIndicator extends HTMLElement {
+
+	/**
+	 * The list of observed attributes.
+	 */
+	static readonly observedAttributes = ["fade"];
+
+	/**
+	 * The number of concurrent HTTP requests.
+	 */
+	#requestCount = 0;
+
+	/**
+	 * Registers the component.
+	 */
+	static {
+		customElements.define("loading-indicator", this);
+	}
+
+	/**
+	 * Value indicating whether to apply a transition.
+	 */
+	get fade(): boolean {
+		return this.hasAttribute("fade");
+	}
+	set fade(value: boolean) {
+		this.toggleAttribute("fade", value);
+	}
+
+	/**
+	 * Value indicating whether this component is shown.
+	 */
+	get isShown(): boolean {
+		return this.classList.contains("show");
+	}
+
+	/**
+	 * Value indicating whether to initially show this component.
+	 */
+	get open(): boolean {
+		return this.hasAttribute("open");
+	}
+	set open(value: boolean) {
+		this.toggleAttribute("open", 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 "fade": this.#updateFade(newValue != null); break;
+			// No default
+		}
+	}
+
+	/**
+	 * Method invoked when this component is connected.
+	 */
+	connectedCallback(): void {
+		this.#requestCount = 0;
+		if (this.open) this.show();
+	}
+
+	/**
+	 * Hides this loading indicator.
+	 * @param options Value indicating whether to force the loading indicator to hide.
+	 */
+	hide(options: {force?: boolean} = {}): void {
+		this.#requestCount--;
+		if (this.#requestCount <= 0 || options.force) {
+			this.#requestCount = 0;
+			this.classList.add("hide");
+			this.classList.remove("show");
+		}
+	}
+
+	/**
+	 * Shows this loading indicator.
+	 */
+	show(): void {
+		this.#requestCount++;
+		this.classList.remove("hide");
+		this.classList.add("show");
+	}
+
+	/**
+	 * Updates the value indicating whether to apply a transition.
+	 * @param value The new value.
+	 */
+	#updateFade(value: boolean): void {
+		this.classList.toggle("fade", value);
+	}
+}
+
+/**
+ * Declaration merging.
+ */
+declare global {
+
+	/**
+	 * The map of HTML tag names.
+	 */
+	interface HTMLElementTagNameMap {
+		"loading-indicator": LoadingIndicator;
+	}
+}