@cedx/ui 0.1.0

package/src/Client/Components/Toast.ts

@@ -0,0 +1,319 @@
+import {Toast as BootstrapToast} from "bootstrap";
+import {Context, cssClass, icon} from "../Context.js";
+
+/**
+ * Represents a notification.
+ */
+export class Toast extends HTMLElement {
+
+	/**
+	 * The list of observed attributes.
+	 */
+	static readonly observedAttributes = ["autohide", "caption", "context", "culture", "delay", "fade", "icon"];
+
+	/**
+	 * The time units.
+	 */
+	static readonly #timeUnits: Intl.RelativeTimeFormatUnit[] = ["second", "minute", "hour"];
+
+	/**
+	 * The abort controller used to remove the event listeners.
+	 */
+	#abortController: AbortController|null = null;
+
+	/**
+	 * The formatter used to format the relative time.
+	 */
+	#formatter!: Intl.RelativeTimeFormat;
+
+	/**
+	 * The time at which this component was initially shown.
+	 */
+	#initialTime = Date.now();
+
+	/**
+	 * The timer identifier.
+	 */
+	#timer = 0;
+
+	/**
+	 * The underlying Bootstrap toast.
+	 */
+	#toast!: BootstrapToast;
+
+	/**
+	 * Registers the component.
+	 */
+	static {
+		customElements.define("toaster-item", this);
+	}
+
+	/**
+	 * Value indicating whether to automatically hide this toast.
+	 */
+	get autoHide(): boolean {
+		return this.hasAttribute("autohide");
+	}
+	set autoHide(value: boolean) {
+		this.toggleAttribute("autohide", value);
+	}
+
+	/**
+	 * The child content displayed in the body.
+	 */
+	set body(value: DocumentFragment) { // eslint-disable-line accessor-pairs
+		this.querySelector(".toast-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);
+	}
+
+	/**
+	 * A contextual modifier.
+	 */
+	get context(): Context {
+		const value = this.getAttribute("context") as Context;
+		return Object.values(Context).includes(value) ? value : Context.Info;
+	}
+	set context(value: Context) {
+		this.setAttribute("context", value);
+	}
+
+	/**
+	 * The culture used to format the relative time.
+	 */
+	get culture(): Intl.Locale {
+		const value = this.getAttribute("culture") ?? "";
+		return new Intl.Locale(value.trim() || navigator.language);
+	}
+	set culture(value: Intl.Locale) {
+		this.setAttribute("culture", value.toString());
+	}
+
+	/**
+	 * The delay, in milliseconds, to hide this toast.
+	 */
+	get delay(): number {
+		const value = Number(this.getAttribute("delay"));
+		return Math.max(0, Number.isNaN(value) ? 5_000 : value);
+	}
+	set delay(value: number) {
+		this.setAttribute("delay", value.toString());
+	}
+
+	/**
+	 * The time elapsed since this component was initially shown, in milliseconds.
+	 */
+	get elapsedTime(): number {
+		return Date.now() - this.#initialTime;
+	}
+
+	/**
+	 * Value indicating whether to apply a transition.
+	 */
+	get fade(): boolean {
+		return this.hasAttribute("fade");
+	}
+	set fade(value: boolean) {
+		this.toggleAttribute("fade", value);
+	}
+
+	/**
+	 * The icon displayed next to the caption.
+	 */
+	get icon(): string|null {
+		const value = this.getAttribute("icon") ?? "";
+		return value.trim() || null;
+	}
+	set icon(value: string|null) {
+		if (value) this.setAttribute("icon", value);
+		else this.removeAttribute("icon");
+	}
+
+	/**
+	 * 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 "autohide": this.#updateAutoHide(newValue != null); break;
+			case "caption": this.#updateCaption(newValue ?? ""); break;
+			case "context": this.#updateContext(Object.values(Context).includes(newValue as Context) ? newValue as Context : Context.Info); break;
+			case "culture": this.#formatter = new Intl.RelativeTimeFormat((newValue ?? "").trim() || navigator.language, {style: "long"}); break;
+			case "delay": this.#updateDelay(Number(newValue)); break;
+			case "fade": this.#updateFade(newValue != null); break;
+			case "icon": this.#updateIcon(newValue); break;
+			// No default
+		}
+	}
+
+	/**
+	 * Closes this toast.
+	 */
+	close(): void {
+		this.#toast.hide();
+	}
+
+	/**
+	 * Method invoked when this component is connected.
+	 */
+	connectedCallback(): void {
+		this.#abortController = new AbortController;
+
+		const root = this.firstElementChild!;
+		root.addEventListener("hide.bs.toast", () => this.#stopTimer(), {signal: this.#abortController.signal});
+		root.addEventListener("show.bs.toast", () => this.#startTimer(), {signal: this.#abortController.signal});
+
+		this.#toast = new BootstrapToast(root);
+		if (this.open) this.show();
+	}
+
+	/**
+	 * Method invoked when this component is disconnected.
+	 */
+	disconnectedCallback(): void {
+		this.#stopTimer();
+		this.#abortController?.abort();
+		this.#toast.dispose();
+	}
+
+	/**
+	 * Shows this toast.
+	 */
+	show(): void {
+		if (!this.#toast.isShown()) {
+			this.#initialTime = Date.now();
+			this.#updateElapsedTime();
+		}
+
+		this.#toast.show();
+	}
+
+	/**
+	 * Formats the specified elapsed time.
+	 * @param elapsed The elapsed time, in seconds.
+	 * @returns The formated time.
+	 */
+	#formatTime(elapsed: number): string {
+		let index = 0;
+		while (elapsed > 60 && index < Toast.#timeUnits.length) {
+			elapsed /= 60;
+			index++;
+		}
+
+		return this.#formatter.format(Math.ceil(-elapsed), Toast.#timeUnits[index]);
+	}
+
+	/**
+	 * Starts the timer.
+	 */
+	#startTimer(): void {
+		this.#timer = window.setInterval(() => this.#updateElapsedTime(), 1_000);
+	}
+
+	/**
+	 * Stops the timer.
+	 */
+	#stopTimer(): void {
+		clearInterval(this.#timer);
+	}
+
+	/**
+	 * Updates the value indicating whether to automatically hide this toast.
+	 * @param value The new value.
+	 */
+	#updateAutoHide(value: boolean): void {
+		(this.firstElementChild! as HTMLElement).dataset.bsAutohide = value ? "true" : "false";
+	}
+
+	/**
+	 * Updates the title displayed in the header.
+	 * @param value The new value.
+	 */
+	#updateCaption(value: string): void {
+		this.querySelector(".toast-header b")!.textContent = value.trim();
+	}
+
+	/**
+	 * Updates the contextual modifier.
+	 * @param value The new value.
+	 */
+	#updateContext(value: Context): void {
+		const contexts = Object.values(Context);
+
+		let {classList} = this.querySelector(".toast-header")!;
+		classList.remove(...contexts.map(context => `toast-header-${cssClass(context)}`));
+		classList.add(`toast-header-${cssClass(value)}`);
+
+		({classList} = this.querySelector(".toast-header .icon")!);
+		classList.remove(...contexts.map(context => `text-${cssClass(context)}`));
+		classList.add(`text-${cssClass(value)}`);
+
+		if (!this.icon) this.#updateIcon(icon(value));
+	}
+
+	/**
+	 * Updates the delay to hide the toast.
+	 * @param value The new value.
+	 */
+	#updateDelay(value: number): void {
+		const delay = Math.max(0, Number.isNaN(value) ? 5_000 : value);
+		(this.firstElementChild! as HTMLElement).dataset.bsDelay = delay.toString();
+	}
+
+	/**
+	 * Updates the label corresponding to the elapsed time.
+	 */
+	#updateElapsedTime(): void {
+		const {elapsedTime} = this;
+		this.querySelector(".toast-header small")!.textContent = elapsedTime > 0 ? this.#formatTime(elapsedTime / 1_000) : "";
+	}
+
+	/**
+	 * Updates the value indicating whether to apply a transition.
+	 * @param value The new value.
+	 */
+	#updateFade(value: boolean): void {
+		(this.firstElementChild! as HTMLElement).dataset.bsAnimation = value ? "true" : "false";
+	}
+
+	/**
+	 * Updates the icon displayed next to the caption.
+	 * @param value The new value.
+	 */
+	#updateIcon(value: string|null): void {
+		this.querySelector(".toast-header .icon")!.textContent = (value ?? "").trim() || icon(this.context);
+	}
+}
+
+/**
+ * Declaration merging.
+ */
+declare global {
+
+	/**
+	 * The map of HTML tag names.
+	 */
+	interface HTMLElementTagNameMap {
+		"toaster-item": Toast;
+	}
+}

package/src/Client/Components/Toaster.ts

@@ -0,0 +1,224 @@
+import {Context} from "../Context.js";
+import {Position, cssClass} from "../Position.js";
+
+/**
+ * Represents a notification.
+ */
+export interface IToast {
+
+	/**
+	 * Value indicating whether to automatically hide the toast.
+	 */
+	autoHide?: boolean;
+
+	/**
+	 * The child content displayed in the body.
+	 */
+	body: DocumentFragment;
+
+	/**
+	 * The title displayed in the header.
+	 */
+	caption: string;
+
+	/**
+	 * The default contextual modifier.
+	 */
+	context?: Context;
+
+	/**
+	 * The culture used to format the relative time.
+	 */
+	culture?: Intl.Locale;
+
+	/**
+	 * The delay, in milliseconds, to hide the toast.
+	 */
+	delay?: number;
+
+	/**
+	 * Value indicating whether to apply a transition.
+	 */
+	fade?: boolean;
+
+	/**
+	 * The icon displayed next to the caption.
+	 */
+	icon?: string;
+}
+
+/**
+ * Manages the notifications.
+ */
+export class Toaster extends HTMLElement {
+
+	/**
+	 * The list of observed attributes.
+	 */
+	static readonly observedAttributes = ["position"];
+
+	/**
+	 * The template for a toast.
+	 */
+	readonly #toastTemplate = this.querySelector("template")!.content;
+
+	/**
+	 * Creates a new toaster.
+	 */
+	constructor() {
+		super();
+		for (const toast of this.querySelectorAll("toaster-item")) toast.addEventListener("hidden.bs.toast", () => toast.remove());
+	}
+
+	/**
+	 * Registers the component.
+	 */
+	static {
+		customElements.define("toaster-container", this);
+	}
+
+	/**
+	 * Value indicating whether to automatically hide the toasts.
+	 */
+	get autoHide(): boolean {
+		return this.hasAttribute("autohide");
+	}
+	set autoHide(value: boolean) {
+		this.toggleAttribute("autohide", value);
+	}
+
+	/**
+	 * The default contextual modifier.
+	 */
+	get context(): Context {
+		const value = this.getAttribute("context") as Context;
+		return Object.values(Context).includes(value) ? value : Context.Info;
+	}
+	set context(value: Context) {
+		this.setAttribute("context", value);
+	}
+
+	/**
+	 * The default culture used to format the relative times.
+	 */
+	get culture(): Intl.Locale {
+		const value = this.getAttribute("culture") ?? "";
+		return new Intl.Locale(value.trim() || navigator.language);
+	}
+	set culture(value: Intl.Locale) {
+		this.setAttribute("culture", value.toString());
+	}
+
+	/**
+	 * The default delay, in milliseconds, to hide the toasts.
+	 */
+	get delay(): number {
+		const value = Number(this.getAttribute("delay"));
+		return Math.max(0, Number.isNaN(value) ? 5_000 : value);
+	}
+	set delay(value: number) {
+		this.setAttribute("delay", value.toString());
+	}
+
+	/**
+	 * Value indicating whether to apply a transition.
+	 */
+	get fade(): boolean {
+		return this.hasAttribute("fade");
+	}
+	set fade(value: boolean) {
+		this.toggleAttribute("fade", value);
+	}
+
+	/**
+	 * The default icon displayed next to the captions.
+	 */
+	get icon(): string|null {
+		const value = this.getAttribute("icon") ?? "";
+		return value.trim() || null;
+	}
+	set icon(value: string|null) {
+		if (value) this.setAttribute("icon", value);
+		else this.removeAttribute("icon");
+	}
+
+	/**
+	 * The toaster placement.
+	 */
+	get position(): Position {
+		const value = this.getAttribute("position") as Position;
+		return Object.values(Position).includes(value) ? value : Position.BottomEnd;
+	}
+	set position(value: Position) {
+		this.setAttribute("position", 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 "position": this.#updatePosition(Object.values(Position).includes(newValue as Position) ? newValue as Position : Position.BottomEnd); break;
+			// No default
+		}
+	}
+
+	/**
+	 * Shows a toast.
+	 * @param context The contextual modifier.
+	 * @param caption The title displayed in the toast header.
+	 * @param message The child content displayed in the toast body.
+	 */
+	notify(context: Context, caption: string, message: DocumentFragment): void {
+		return this.show({body: message, caption, context});
+	}
+
+	/**
+	 * Shows a toast.
+	 * @param toast The toast to show.
+	 */
+	show(toast: IToast): void {
+		const item = document.createElement("toaster-item");
+		const childContent = (this.#toastTemplate.cloneNode(true) as DocumentFragment).querySelector(".toast")!;
+		childContent.addEventListener("hidden.bs.toast", () => item.remove());
+		item.appendChild(childContent);
+
+		item.autoHide = toast.autoHide ?? this.autoHide;
+		item.body = toast.body;
+		item.caption = toast.caption;
+		item.context = toast.context ?? this.context;
+		item.culture = toast.culture ?? this.culture;
+		item.delay = toast.delay ?? this.delay;
+		item.fade = toast.fade ?? this.fade;
+		item.icon = toast.icon ?? this.icon;
+
+		this.firstElementChild!.appendChild(item);
+		item.show();
+	}
+
+	/**
+	 * Updates the toaster placement.
+	 * @param value The new value.
+	 */
+	#updatePosition(value: Position): void {
+		const {classList} = this.firstElementChild!;
+		classList.remove(...Object.values(Position).flatMap(position => cssClass(position).split(" ")));
+		classList.add(...cssClass(value).split(" "));
+	}
+}
+
+/**
+ * Declaration merging.
+ */
+declare global {
+
+	/**
+	 * The map of HTML tag names.
+	 */
+	interface HTMLElementTagNameMap {
+		"toaster-container": Toaster;
+	}
+}

package/src/Client/Components/TypeAhead.ts

@@ -0,0 +1,153 @@
+/**
+ * A dynamic list of suggested values for an associated control.
+ */
+export class TypeAhead extends HTMLElement {
+
+	/**
+	 * The list of observed attributes.
+	 */
+	static readonly observedAttributes = ["list", "query"];
+
+	/**
+	 * The debounced handler used to look up the query.
+	 */
+	#debounced: (value: string) => void = () => { /* Noop */ };
+
+	/**
+	 * The previous query.
+	 */
+	#previousQuery = "";
+
+	/**
+	 * Registers the component.
+	 */
+	static {
+		customElements.define("type-ahead", this);
+	}
+
+	/**
+	 * The delay in milliseconds to wait before triggering autocomplete suggestions.
+	 */
+	get delay(): number {
+		const value = Number(this.getAttribute("delay"));
+		return Math.max(0, Number.isNaN(value) ? 300 : value);
+	}
+	set delay(value: number) {
+		this.setAttribute("delay", value.toString());
+	}
+
+	/**
+	 * The function invoked when the query has been changed.
+	 */
+	set handler(callback: (query: string) => Promise<string[]>) { // eslint-disable-line accessor-pairs
+		this.#debounced = this.#debounce(async query => { // eslint-disable-line @typescript-eslint/no-misused-promises
+			try { this.#updateItems(await callback(query)); }
+			catch { this.#updateItems([]); }
+		}, this.delay);
+	}
+
+	/**
+	 * The data list identifier.
+	 */
+	get list(): string {
+		return (this.getAttribute("list") ?? "").trim();
+	}
+	set list(value: string) {
+		this.setAttribute("list", value);
+	}
+
+	/**
+	 * The minimum character length needed before triggering autocomplete suggestions.
+	 */
+	get minLength(): number {
+		const value = Number(this.getAttribute("minlength"));
+		return Math.max(1, Number.isNaN(value) ? 1 : value);
+	}
+	set minLength(value: number) {
+		this.setAttribute("minlength", value.toString());
+	}
+
+	/**
+	 * The query to look up.
+	 */
+	get query(): string {
+		return (this.getAttribute("query") ?? "").trim();
+	}
+	set query(value: string) {
+		this.setAttribute("query", 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 "list": this.#updateList(newValue ?? ""); break;
+			case "query": this.#updateQuery(newValue ?? ""); break;
+			// No default
+		}
+	}
+
+	/**
+	 * Postpones the invocation of the specified callback until after a given delay has elapsed since the last time it was invoked.
+	 * @param callback The function to debounce.
+	 * @param delay The delay to wait, in milliseconds.
+	 * @returns The debounced function.
+	 */
+	#debounce(callback: (value: string) => void, delay: number): (value: string) => void {
+		let timer = 0;
+		return value => {
+			if (timer) clearTimeout(timer);
+			timer = window.setTimeout(callback, delay, value);
+		};
+	}
+
+	/**
+	 * Updates the identifier of the underlying data list.
+	 * @param value The new value.
+	 */
+	#updateList(value: string): void {
+		this.firstElementChild!.id = value.trim();
+	}
+
+	/**
+	 * Updates the query to look up.
+	 * @param value The new value.
+	 */
+	#updateQuery(value: string): void {
+		const query = value.trim();
+		if (query != this.#previousQuery) {
+			this.#previousQuery = query;
+			if (query.length < this.minLength) this.#updateItems([]);
+			else this.#debounced(query);
+		}
+	}
+
+	/**
+	 * Updates the items of the underlying data list.
+	 * @param values The new values.
+	 */
+	#updateItems(values: string[]): void {
+		this.firstElementChild!.replaceChildren(...values.map(value => {
+			const option = document.createElement("option");
+			option.value = value;
+			return option;
+		}));
+	}
+}
+
+/**
+ * Declaration merging.
+ */
+declare global {
+
+	/**
+	 * The map of HTML tag names.
+	 */
+	interface HTMLElementTagNameMap {
+		"type-ahead": TypeAhead;
+	}
+}