@cedx/base 0.11.0 → 0.13.0

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

@@ -0,0 +1,252 @@
+import {Duration} from "@cedx/base/Duration.js";
+import {Context, getIcon, toCss} from "@cedx/base/UI/Context.js";
+import {Toast as BootstrapToast} from "bootstrap";
+
+/**
+ * Manages the notification messages.
+ */
+export class Toast extends HTMLElement {
+
+	/**
+	 * The list of observed attributes.
+	 */
+	static readonly observedAttributes = ["caption", "context", "culture", "icon"];
+
+	/**
+	 * The time units.
+	 */
+	static readonly #timeUnits: Intl.RelativeTimeFormatUnit[] = ["second", "minute", "hour"];
+
+	/**
+	 * The formatter used to format the relative time.
+	 */
+	#formatter!: Intl.RelativeTimeFormat;
+
+	/**
+	 * The toast header.
+	 */
+	readonly #header = this.querySelector(".toast-header")!;
+
+	/**
+	 * 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 apply a fade transition.
+	 */
+	get animation(): boolean {
+		return this.hasAttribute("animation");
+	}
+	set animation(value: boolean) {
+		if (value) this.setAttribute("animation", "");
+		else this.removeAttribute("animation");
+	}
+
+	/**
+	 * Value indicating whether to automatically hide the notification.
+	 */
+	get autoHide(): boolean {
+		return this.hasAttribute("autohide");
+	}
+	set autoHide(value: boolean) {
+		if (value) this.setAttribute("autohide", "");
+		else this.removeAttribute("autohide");
+	}
+
+	/**
+	 * 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 the notification.
+	 */
+	get delay(): number {
+		const value = Number(this.getAttribute("delay"));
+		return Math.max(1, 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;
+	}
+
+	/**
+	 * The icon displayed next to the caption.
+	 */
+	get icon(): string {
+		const value = this.getAttribute("icon") ?? "";
+		return value.trim() || getIcon(Context.Info);
+	}
+	set icon(value: string) {
+		this.setAttribute("icon", 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 "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 "icon":
+				this.#updateIcon(newValue ?? "")
+				break;
+			// No default
+		}
+	}
+
+	/**
+	 * Method invoked when this component is connected.
+	 */
+	connectedCallback(): void {
+		const toast = this.querySelector(".toast")!;
+		toast.addEventListener("hidden.bs.toast", () => clearInterval(this.#timer));
+		toast.addEventListener("show.bs.toast", () => this.#timer = window.setInterval(this.#updateElapsedTime, Duration.Second));
+
+		const {animation, autoHide: autohide, delay} = this;
+		this.#toast = new BootstrapToast(toast, {animation, autohide, delay});
+	}
+
+	/**
+	 * Method invoked when this component is disconnected.
+	 */
+	disconnectedCallback(): void {
+		clearInterval(this.#timer);
+		this.#toast.dispose();
+	}
+
+	/**
+	 * Hides this toast.
+	 */
+	hide(): void {
+		this.#toast.hide();
+	}
+
+	/**
+	 * 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]);
+	}
+
+	/**
+	 * Updates the title displayed in the header.
+	 * @param value The new value.
+	 */
+	#updateCaption(value: string): void {
+		this.#header.querySelector("b")!.textContent = value.trim();
+	}
+
+	/**
+	 * Updates the title displayed in the header.
+	 * @param value The new value.
+	 */
+	#updateContext(value: Context): void {
+		const contexts = Object.values(Context);
+
+		let {classList} = this.#header;
+		classList.remove(...contexts.map(context => `toast-header-${toCss(context)}`));
+		classList.add(`toast-header-${value}`);
+
+		({classList} = this.#header.querySelector(".icon")!);
+		classList.remove(...contexts.map(context => `text-${toCss(context)}`));
+		classList.add(`text-${value}`);
+	}
+
+	/**
+	 * Updates the label corresponding to the elapsed time.
+	 */
+	readonly #updateElapsedTime: () => void = () => {
+		const {elapsedTime} = this;
+		this.#header.querySelector("small")!.textContent = elapsedTime > 0 ? this.#formatTime(elapsedTime / Duration.Second) : "";
+	};
+
+	/**
+	 * Updates the icon displayed next to the caption.
+	 * @param value The new value.
+	 */
+	#updateIcon(value: string): void {
+		this.#header.querySelector(".icon")!.textContent = value.trim() || getIcon(Context.Info);
+	}
+}

package/src/Client/UI/Context.ts

@@ -6,22 +6,22 @@ export const Context = Object.freeze({
 	/**
 	 * A danger.
 	 */
-	Danger: "danger",
+	Danger: "Danger",
 
 	/**
 	 * A warning.
 	 */
-	Warning: "warning",
+	Warning: "Warning",
 
 	/**
 	 * An information.
 	 */
-	Info: "info",
+	Info: "Info",
 
 	/**
 	 * A success.
 	 */
-	Success: "success"
+	Success: "Success"
 });
 
 /**
@@ -42,3 +42,12 @@ export function getIcon(context: Context): string {
 		default: return "info";
 	}
 }
+
+/**
+ * Returns the CSS representation of the specified context.
+ * @param context The context.
+ * @returns The CSS representation of the specified context.
+ */
+export function toCss(context: Context): string {
+	return context.toLowerCase();
+}

package/src/Client/UI/Position.ts

@@ -0,0 +1,74 @@
+/**
+ * Defines the position of an element.
+ */
+export const Position = Object.freeze({
+
+	/**
+	 * Top left.
+	 */
+	TopStart: "TopStart",
+
+	/**
+	 * Top center.
+	 */
+	TopCenter: "TopCenter",
+
+	/**
+	 * Top right.
+	 */
+	TopEnd: "TopEnd",
+
+	/**
+	 * Middle left.
+	 */
+	MiddleStart: "MiddleStart",
+
+	/**
+	 * Middle center.
+	 */
+	MiddleCenter: "MiddleCenter",
+
+	/**
+	 * Middle right.
+	 */
+	MiddleEnd: "MiddleEnd",
+
+	/**
+	 * Bottom left.
+	 */
+	BottomStart: "BottomStart",
+
+	/**
+	 * Bottom center.
+	 */
+	BottomCenter: "BottomCenter",
+
+	/**
+	 * Bottom right.
+	 */
+	BottomEnd: "BottomEnd"
+});
+
+/**
+ * Defines the placement of an element.
+ */
+export type Position = typeof Position[keyof typeof Position];
+
+/**
+ * Returns the CSS representation of the specified position.
+ * @param position The position.
+ * @returns The CSS representation of the specified position.
+ */
+export function toCss(position: Position): string {
+	switch (position) {
+		case Position.TopCenter: return "top-0 start-50 translate-middle-x";
+		case Position.TopEnd: return "top-0 end-0";
+		case Position.MiddleStart: return "top-50 start-0 translate-middle-y";
+		case Position.MiddleCenter: return "top-50 start-50 translate-middle";
+		case Position.MiddleEnd: return "top-50 end-0 translate-middle-y";
+		case Position.BottomStart: return "bottom-0 start-0";
+		case Position.BottomCenter: return "bottom-0 start-50 translate-middle-x";
+		case Position.BottomEnd: return "bottom-0 end-0";
+		default: return "top-0 start-0";
+	}
+}

package/src/Client/UI/Size.ts

@@ -1,40 +1,56 @@
 /**
- * Defines the size of a component.
+ * Defines the size of an element.
  */
 export const Size = Object.freeze({
 
 	/**
 	 * An extra small size.
 	 */
-	ExtraSmall: "xs",
+	ExtraSmall: "ExtraSmall",
 
 	/**
 	 * A small size.
 	 */
-	Small: "sm",
+	Small: "Small",
 
 	/**
 	 * A medium size.
 	 */
-	Medium: "md",
+	Medium: "Medium",
 
 	/**
 	 * A large size.
 	 */
-	Large: "lg",
+	Large: "Large",
 
 	/**
 	 * An extra large size.
 	 */
-	ExtraLarge: "xl",
+	ExtraLarge: "ExtraLarge",
 
 	/**
 	 * An extra extra large size.
 	 */
-	ExtraExtraLarge: "xxl"
+	ExtraExtraLarge: "ExtraExtraLarge"
 });
 
 /**
- * Defines the size of a component.
+ * Defines the size of an element.
  */
 export type Size = typeof Size[keyof typeof Size];
+
+/**
+ * Returns the CSS representation of the specified size.
+ * @param size The size.
+ * @returns The CSS representation of the specified size.
+ */
+export function toCss(size: Size): string {
+	switch (size) {
+		case Size.ExtraSmall: return "xs";
+		case Size.Small: return "sm";
+		case Size.Large: return "lg";
+		case Size.ExtraLarge: return "xl";
+		case Size.ExtraExtraLarge: return "xxl";
+		default: return "md";
+	}
+}

package/src/Client/UI/Variant.ts

@@ -6,25 +6,34 @@ export const Variant = Object.freeze({
 	/**
 	 * A dark variant.
 	 */
-	Dark: "dark",
+	Dark: "Dark",
 
 	/**
 	 * A light variant.
 	 */
-	Light: "light",
+	Light: "Light",
 
 	/**
 	 * A primary variant.
 	 */
-	Primary: "primary",
+	Primary: "Primary",
 
 	/**
 	 * A secondary variant.
 	 */
-	Secondary: "secondary"
+	Secondary: "Secondary"
 });
 
 /**
  * Defines tone variants.
  */
 export type Variant = typeof Variant[keyof typeof Variant];
+
+/**
+ * Returns the CSS representation of the specified variant.
+ * @param variant The variant.
+ * @returns The CSS representation of the specified variant.
+ */
+export function toCss(variant: Variant): string {
+	return variant.toLowerCase();
+}

package/src/Client/UI/Components/MessageBox.old

@@ -1,242 +0,0 @@
-import {Context, getIcon} from "../Context.js";
-import {Variant} from "../Variant.js";
-
-/**
- * Specifies the return value of a message box.
- */
-export const MessageBoxResult = Object.freeze({
-
-	/**
-	 * The message box does not return any value.
-	 */
-	None: "",
-
-	/**
-	 * The return value of the message box is "OK".
-	 */
-	OK: "OK",
-
-	/**
-	 * The return value of the message box is "Cancel".
-	 */
-	Cancel: "Cancel"
-});
-
-/**
- * Specifies the return value of a message box.
- */
-export type MessageBoxResult = typeof MessageBoxResult[keyof typeof MessageBoxResult];
-
-/**
- * Displays a message window, also known as dialog box, which presents a message to the user.
- */
-export class MessageBox extends HTMLElement {
-
-	/**
-	 * Value indicating whether to vertically center this message box.
-	 */
-	@property({type: Boolean}) centered = false;
-
-	/**
-	 * The buttons displayed in the footer.
-	 */
-	@state() private buttons: MessageBoxButton[] = [];
-
-	/**
-	 * The title displayed in the header.
-	 */
-	@state() private caption = "";
-
-	/**
-	 * The message displayed in the body.
-	 */
-	@state() private content: TemplateResult = html``;
-
-	/**
-	 * A contextual modifier.
-	 */
-	@state() private context: Context|null = null;
-
-	/**
-	 * The icon displayed next to the body.
-	 */
-	@state() private icon = "";
-
-	/**
-	 * The root element.
-	 */
-	@query("dialog", true) private readonly root!: HTMLDialogElement;
-
-	/**
-	 * The function invoked to return the dialog box result.
-	 */
-	#resolve: (value: string) => void = () => { /* Noop */ };
-
-	/**
-	 * Opens an alert dialog with the specified message and an "OK" button.
-	 * @param caption The title displayed in the header.
-	 * @param message The message to show.
-	 * @param options The message box options.
-	 * @returns Resolves with the value of the clicked button.
-	 */
-	alert(caption: string, message: TemplateResult, options: MessageBoxOptions = {}): Promise<string> {
-		const context = options.context ?? Context.Warning;
-		return this.show(message, {
-			buttons: options.buttons ?? [{label: "OK", value: MessageBoxResult.OK}],
-			caption,
-			context,
-			icon: options.icon ?? getIcon(context)
-		});
-	}
-
-	/**
-	 * Closes the message box.
-	 * @param result The message box result.
-	 */
-	close(result: MessageBoxResult = MessageBoxResult.None): void {
-		this.root.close(result);
-	}
-
-	/**
-	 * Opens a confirmation dialog with the specified message and two buttons, "OK" and "Cancel".
-	 * @param caption The title displayed in the header.
-	 * @param message The message to show.
-	 * @param options The message box options.
-	 * @returns Resolves with the value of the clicked button.
-	 */
-	confirm(caption: string, message: TemplateResult, options: MessageBoxOptions = {}): Promise<string> {
-		const context = options.context ?? Context.Warning;
-		return this.show(message, {
-			caption,
-			context,
-			icon: options.icon ?? getIcon(context),
-			buttons: options.buttons ?? [
-				{label: "OK", value: MessageBoxResult.OK},
-				{label: "Annuler", value: MessageBoxResult.Cancel, variant: Variant.Secondary}
-			]
-		});
-	}
-
-	/**
-	 * Opens a modal dialog with the specified message and options.
-	 * @param message The message to show.
-	 * @param options The message box options.
-	 * @returns Resolves with the value of the clicked button.
-	 */
-	show(message: TemplateResult, options: MessageBoxOptions = {}): Promise<string> {
-		this.buttons = options.buttons ?? [];
-		this.caption = options.caption ?? "";
-		this.content = message;
-		this.context = options.context ?? null;
-		this.icon = options.icon ?? "";
-
-		this.root.returnValue = MessageBoxResult.None;
-		this.root.showModal();
-		this.root.querySelector<HTMLButtonElement>(".btn-close")?.blur();
-
-		const {promise, resolve} = Promise.withResolvers<string>();
-		this.#resolve = resolve;
-		return promise;
-	}
-
-	/**
-	 * Renders this component.
-	 * @returns The view template.
-	 */
-	protected override render(): TemplateResult {
-		const centered = classMap({"modal-dialog-centered": this.centered});
-		return html`
-			<dialog class="modal modal-dialog modal-dialog-scrollable ${centered}" @click=${this.#onDialogClick} @close=${this.#onDialogClose}>
-				<form class="modal-content" method="dialog">
-					<div class="modal-header user-select-none">
-						${when(this.caption, () => html`<h1 class="modal-title fs-5">${this.caption}</h1>`)}
-						<button class="btn-close"></button>
-					</div>
-					<div class="modal-body d-flex">
-						${when(this.icon, () => html`
-							<i class="icon icon-fill fs-1 fw-semibold me-2 ${classMap({[`text-${this.context}`]: this.context ?? ""})}">${this.icon}</i>
-						`)}
-						<div class="flex-grow-1">${this.content}</div>
-					</div>
-					${when(this.buttons.length, () => html`
-						<div class="modal-footer user-select-none">
-							${this.buttons.map(button => html`
-								<button class="btn btn-${button.variant ?? Variant.Primary}" value=${button.value ?? MessageBoxResult.None}>
-									${when(button.icon, () => html`<i class="icon icon-fill ${classMap({"me-1": button.label ?? ""})}">${button.icon}</i>`)}
-									${button.label}
-								</button>
-							`)}
-						</div>
-					`)}
-				</form>
-			</dialog>
-		`;
-	}
-
-	/**
-	 * Handles the `click` event.
-	 * @param event The dispatched event.
-	 */
-	#onDialogClick(event: Event): void {
-		if (event.target == this.root) this.close();
-	}
-
-	/**
-	 * Handles the `close` event.
-	 */
-	#onDialogClose(): void {
-		this.#resolve(this.root.returnValue);
-	}
-}
-
-/**
- * A message box button.
- */
-export type MessageBoxButton = Partial<{
-
-	/**
-	 * The button icon.
-	 */
-	icon: string;
-
-	/**
-	 * The button label.
-	 */
-	label: string;
-
-	/**
-	 * The button value.
-	 */
-	value: string;
-
-	/**
-	 * A tone variant.
-	 */
-	variant: Context|Variant;
-}>;
-
-/**
- * Defines the options of a {@link MessageBox} instance.
- */
-export type MessageBoxOptions = Partial<{
-
-	/**
-	 * The buttons displayed in the footer.
-	 */
-	buttons: MessageBoxButton[];
-
-	/**
-	 * The title displayed in the header.
-	 */
-	caption: string;
-
-	/**
-	 * A contextual modifier.
-	 */
-	context: Context;
-
-	/**
-	 * The icon displayed next to the body.
-	 */
-	icon: string;
-}>;