@cedx/ui 0.1.0

package/src/Client/Context.ts

@@ -0,0 +1,53 @@
+/**
+ * Defines contextual modifiers.
+ */
+export const Context = Object.freeze({
+
+	/**
+	 * A danger.
+	 */
+	Danger: "Danger",
+
+	/**
+	 * A warning.
+	 */
+	Warning: "Warning",
+
+	/**
+	 * An information.
+	 */
+	Info: "Info",
+
+	/**
+	 * A success.
+	 */
+	Success: "Success"
+});
+
+/**
+ * Defines contextual modifiers.
+ */
+export type Context = typeof Context[keyof typeof Context];
+
+/**
+ * Returns the CSS class of the specified context.
+ * @param context The context.
+ * @returns The CSS class of the specified context.
+ */
+export function cssClass(context: Context): string {
+	return context.toLowerCase();
+}
+
+/**
+ * Gets the icon corresponding to the specified context.
+ * @param context The context.
+ * @returns The icon corresponding to the specified context.
+ */
+export function icon(context: Context): string {
+	switch (context) {
+		case Context.Danger: return "error";
+		case Context.Success: return "check_circle";
+		case Context.Warning: return "warning";
+		default: return "info";
+	}
+}

package/src/Client/DialogResult.ts

@@ -0,0 +1,35 @@
+/**
+ * Specifies common return values of a dialog box.
+ */
+export const DialogResult = Object.freeze({
+
+	/**
+	 * The dialog box does not return any value.
+	 */
+	None: "",
+
+	/**
+	 * The return value of the dialog box is "OK".
+	 */
+	OK: "OK",
+
+	/**
+	 * The return value of the dialog box is "Cancel".
+	 */
+	Cancel: "Cancel",
+
+	/**
+	 * The return value of the dialog box is "Abort".
+	 */
+	Abort: "Abort",
+
+	/**
+	 * The return value of the dialog box is "Retry".
+	 */
+	Retry: "Retry",
+
+	/**
+	 * The return value of the dialog box is "Ignore".
+	 */
+	Ignore: "Ignore"
+});

package/src/Client/File.ts

@@ -0,0 +1,73 @@
+/**
+ * Downloads the specified file.
+ * @param file The file to be downloaded.
+ */
+export function download(file: File): void {
+	const url = URL.createObjectURL(file);
+	const anchor = document.createElement("a");
+	anchor.download = file.name;
+	anchor.href = url;
+
+	document.body.appendChild(anchor);
+	anchor.click();
+	document.body.removeChild(anchor);
+	URL.revokeObjectURL(url);
+}
+
+/**
+ * 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 open(file: File, options: {newTab?: boolean} = {}): void {
+	const url = URL.createObjectURL(file);
+	if (!options.newTab) {
+		location.assign(url);
+		return;
+	}
+
+	const handle = window.open(url, "_blank");
+	if (!handle)  {
+		location.assign(url);
+		return;
+	}
+
+	const timer = window.setInterval(() => {
+		if (!handle.closed) return;
+		clearInterval(timer);
+		URL.revokeObjectURL(url);
+	}, 5_000);
+}
+
+/**
+ * Prints the specified file.
+ * @param file The file to be printed.
+ */
+export function print(file: File): void {
+	const url = URL.createObjectURL(file);
+	const frame = document.createElement("iframe");
+	frame.addEventListener("load", () => frame.contentWindow?.print());
+	frame.hidden = true;
+	frame.src = url;
+
+	window.addEventListener("focus", () => {
+		document.body.removeChild(frame);
+		URL.revokeObjectURL(url);
+	}, {once: true});
+
+	document.body.appendChild(frame);
+}
+
+/**
+ * Converts the specified file to a data URL.
+ * @param file The file to convert.
+ * @returns The data URL corresponding to the given file.
+ */
+export function toDataUrl(file: File): Promise<URL> {
+	return new Promise((resolve, reject) => {
+		const reader = new FileReader;
+		reader.addEventListener("error", reject);
+		reader.addEventListener("load", () => resolve(new URL(reader.result as string)));
+		reader.readAsDataURL(file);
+	});
+}

package/src/Client/Form.ts

@@ -0,0 +1,55 @@
+/**
+ * The types of form controls that are not text inputs.
+ */
+const nonTextualTypes = new Set<string>(["button", "checkbox", "file", "hidden", "image", "password", "radio", "range", "reset", "submit"]);
+
+/**
+ * Represents a form control.
+ */
+export type FormControl = HTMLInputElement|HTMLSelectElement|HTMLTextAreaElement;
+
+/**
+ * Gets all controls belonging to the specified form.
+ * @param form The form element.
+ * @returns The controls belonging to the specified form.
+ */
+export function getControls(form: HTMLFormElement): FormControl[] {
+	return Array.from(form.elements).filter(isControl);
+}
+
+/**
+ * Returns the first invalid control from the specified form.
+ * @param form The form element.
+ * @returns The first invalid control, or `null` if all controls are valid.
+ */
+export function invalidControl(form: HTMLFormElement): FormControl|null {
+	return form.querySelector(":not(fieldset):invalid");
+}
+
+/**
+ * Returns a value indicating whether the specified element is a form control.
+ * @param element The element to check.
+ * @returns `true` if the specified element is a form control, otherwise `false`.
+ */
+export function isControl(element: Element): element is FormControl {
+	return element instanceof HTMLInputElement || element instanceof HTMLSelectElement || element instanceof HTMLTextAreaElement;
+}
+
+/**
+ * Resets the validity of the specified element.
+ * @param element The element to process.
+ */
+export function resetValidity(element: Element): void {
+	if (element instanceof HTMLFormElement) getControls(element).forEach(control => control.setCustomValidity(""));
+	else if (isControl(element)) element.setCustomValidity("");
+}
+
+/**
+ * Removes whitespace from both ends of the value of the specified element.
+ * @param element The element to process.
+ */
+export function trimControl(element: Element): void {
+	if (element instanceof HTMLFormElement) getControls(element).forEach(trimControl);
+	else if (element instanceof HTMLInputElement && !nonTextualTypes.has(element.type)) element.value = element.value.trim();
+	else if (element instanceof HTMLTextAreaElement) element.value = element.value.trim();
+}

package/src/Client/Htmx.ts

@@ -0,0 +1,13 @@
+import htmx, {type HtmxResponseInfo} from "htmx.org";
+export const Htmx = htmx as unknown as typeof htmx.default;
+
+/**
+ * Provides details about an `htmx` event.
+ */
+export type HtmxEventDetail = HtmxResponseInfo & {
+
+	/**
+	 * The element involved in the operation that just occurred.
+	 */
+	elt: Element;
+};

package/src/Client/KeyboardModifiers.ts

@@ -0,0 +1,30 @@
+/**
+ * Enumerates modifier flags for keyboard accelerators.
+ */
+export const KeyboardModifiers = Object.freeze({
+
+	/**
+	 * Indicates no modifier.
+	 */
+	None: 0,
+
+	/**
+	 * Indicates the `Control` modifier.
+	 */
+	Ctrl: 1,
+
+	/**
+	 * Indicates the `Shift` modifier.
+	 */
+	Shift: 2,
+
+	/**
+	 * Indicates the `Alt` modifier (`Option` key on macOS, `Menu` key on Windows).
+	 */
+	Alt: 4,
+
+	/**
+	 * Indicates the `Meta` modifier (`Command` key on macOS, `Windows` key on Windows).
+	 */
+	Meta: 8
+});

package/src/Client/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 class of the specified position.
+ * @param position The position.
+ * @returns The CSS class of the specified position.
+ */
+export function cssClass(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/Size.ts

@@ -0,0 +1,56 @@
+/**
+ * Defines the size of an element.
+ */
+export const Size = Object.freeze({
+
+	/**
+	 * An extra small size.
+	 */
+	ExtraSmall: "ExtraSmall",
+
+	/**
+	 * A small size.
+	 */
+	Small: "Small",
+
+	/**
+	 * A medium size.
+	 */
+	Medium: "Medium",
+
+	/**
+	 * A large size.
+	 */
+	Large: "Large",
+
+	/**
+	 * An extra large size.
+	 */
+	ExtraLarge: "ExtraLarge",
+
+	/**
+	 * An extra extra large size.
+	 */
+	ExtraExtraLarge: "ExtraExtraLarge"
+});
+
+/**
+ * Defines the size of an element.
+ */
+export type Size = typeof Size[keyof typeof Size];
+
+/**
+ * Returns the CSS class of the specified size.
+ * @param size The size.
+ * @returns The CSS class of the specified size.
+ */
+export function cssClass(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/StorageArea.ts

@@ -0,0 +1,20 @@
+/**
+ * Identifies the web storage area.
+ */
+export const StorageArea = Object.freeze({
+
+	/**
+	 * Indicates the local storage.
+	 */
+	Local: "Local",
+
+	/**
+	 * Indicates the session storage.
+	 */
+	Session: "Session"
+});
+
+/**
+ * Identifies the web storage area.
+ */
+export type StorageArea = typeof StorageArea[keyof typeof StorageArea];

package/src/Client/Tags.ts

@@ -0,0 +1,58 @@
+/**
+ * Creates a CSS stylesheet from the specified template literal.
+ * @param fragments The string fragments.
+ * @param values The interpolated values.
+ * @returns The CSS stylesheet corresponding to the specified template literal.
+ */
+export function css(fragments: TemplateStringsArray, ...values: unknown[]): CSSStyleSheet {
+	const styleSheet = new CSSStyleSheet;
+	styleSheet.replaceSync(fragments.length == 1 ? fragments[0] : values.reduce(
+		(fragment: string, value: unknown, index: number) => fragment + stringFromCss(value) + fragments[index + 1],
+		fragments[0]
+	));
+
+	return styleSheet;
+}
+
+/**
+ * Creates a document fragment from the specified template literal.
+ * @param fragments The string fragments.
+ * @param values The interpolated values.
+ * @returns The document fragment corresponding to the specified template literal.
+ */
+export function html(fragments: TemplateStringsArray, ...values: unknown[]): DocumentFragment {
+	return document.createRange().createContextualFragment(fragments.length == 1 ? fragments[0] : values.reduce(
+		(fragment: string, value: unknown, index: number) => fragment + stringFromHtml(value) + fragments[index + 1],
+		fragments[0]
+	));
+}
+
+/**
+ * Converts the specified value to a CSS string.
+ * @param value A value representing a CSS fragment.
+ * @returns The CSS string corresponding to the specified value.
+ */
+function stringFromCss(value: unknown): string {
+	if (!(value instanceof CSSStyleSheet)) {
+		if (Array.isArray(value)) return value.map(stringFromCss).join("\n");
+		return value === null || typeof value == "undefined" ? "" : String(value); // eslint-disable-line @typescript-eslint/no-base-to-string
+	}
+
+	return Array.from(value.cssRules).map(cssRule => cssRule.cssText).join("\n");
+}
+
+/**
+ * Converts the specified value to an HTML string.
+ * @param value A value representing an HTML fragment.
+ * @returns The HTML string corresponding to the specified value.
+ */
+function stringFromHtml(value: unknown): string {
+	if (!(value instanceof DocumentFragment)) {
+		if (Array.isArray(value)) return value.map(stringFromHtml).join("");
+		return value === null || typeof value == "undefined" ? "" : String(value); // eslint-disable-line @typescript-eslint/no-base-to-string
+	}
+
+	const element = document.createElement("div");
+	element.appendChild(value);
+	return element.innerHTML;
+}

package/src/Client/Variant.ts

@@ -0,0 +1,42 @@
+import {Context} from "./Context.js";
+
+/**
+ * Defines tone variants.
+ */
+export const Variant = Object.freeze({
+	...Context,
+
+	/**
+	 * A primary tone.
+	 */
+	Primary: "Primary",
+
+	/**
+	 * A secondary tone.
+	 */
+	Secondary: "Secondary",
+
+	/**
+	 * A light tone.
+	 */
+	Light: "Light",
+
+	/**
+	 * A dark tone.
+	 */
+	Dark: "Dark"
+});
+
+/**
+ * Defines tone variants.
+ */
+export type Variant = typeof Variant[keyof typeof Variant];
+
+/**
+ * Returns the CSS class of the specified variant.
+ * @param variant The variant.
+ * @returns The CSS class of the specified variant.
+ */
+export function cssClass(variant: Variant): string {
+	return variant.toLowerCase();
+}

package/src/Client/ViewportScroller.ts

@@ -0,0 +1,89 @@
+/**
+ * Defines the scrolling options.
+ */
+export type ScrollOptions = Partial<{
+
+	/**
+	 * Value indicating whether scrolling is instant or animates smoothly.
+	 */
+	behavior: ScrollBehavior
+}>;
+
+/**
+ * Manages the scroll position.
+ */
+export class ViewportScroller {
+
+	/**
+	 * The top offset used when scrolling to an element.
+	 */
+	#scrollOffset = -1;
+
+	/**
+	 * The function returning the element used as viewport.
+	 */
+	readonly #viewport: () => Element;
+
+	/**
+	 * Creates a new viewport scroller.
+	 * @param viewport A function that returns the element used as viewport.
+	 */
+	constructor(viewport: () => Element = () => document.scrollingElement ?? document.documentElement) {
+		this.#viewport = viewport;
+	}
+
+	/**
+	 * The top offset used when scrolling to an element.
+	 */
+	get scrollOffset(): number {
+		if (this.#scrollOffset < 0) {
+			const fontSize = Number.parseInt(getComputedStyle(document.body).fontSize, 10);
+			this.#scrollOffset = Number.isNaN(fontSize) ? 0 : fontSize * 2;
+
+			const navbar = document.body.querySelector<HTMLElement>(".navbar");
+			this.#scrollOffset += (navbar?.offsetHeight ?? 0);
+		}
+
+		const actionBar = document.body.querySelector<HTMLElement>("action-bar");
+		return this.#scrollOffset + (actionBar?.offsetHeight ?? 0);
+	}
+
+	/**
+	 * Scrolls to the specified anchor.
+	 * @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 {
+		const element = document.getElementById(anchor) ?? this.#viewport().querySelector(`[name="${anchor}"]`);
+		if (element) this.scrollToElement(element, options);
+	}
+
+	/**
+	 * Scrolls to the specified element.
+	 * @param element The element to scroll to.
+	 * @param options Value indicating whether scrolling is instant or animates smoothly.
+	 */
+	scrollToElement(element: Element, options: ScrollOptions = {}): void {
+		const {left, top} = element.getBoundingClientRect();
+		const {scrollLeft, scrollTop} = this.#viewport();
+		this.scrollToPosition(left + scrollLeft, top + scrollTop - this.scrollOffset, options);
+	}
+
+	/**
+	 * Scrolls to the specified position.
+	 * @param x The pixel along the horizontal axis.
+	 * @param y The pixel along the vertical axis.
+	 * @param options Value indicating whether scrolling is instant or animates smoothly.
+	 */
+	scrollToPosition(x: number, y: number, options: ScrollOptions = {}): void {
+		this.#viewport().scrollTo({left: x, top: y, behavior: options.behavior ?? "auto"});
+	}
+
+	/**
+	 * Scrolls to the top.
+	 * @param options Value indicating whether scrolling is instant or animates smoothly.
+	 */
+	scrollToTop(options: ScrollOptions = {}): void {
+		this.scrollToPosition(0, 0, options);
+	}
+}

package/src/Client/tsconfig.json

@@ -0,0 +1,19 @@
+{
+	"include": ["**/*.ts"],
+	"compilerOptions": {
+		"declaration": true,
+		"declarationMap": true,
+		"erasableSyntaxOnly": true,
+		"incremental": true,
+		"module": "NodeNext",
+		"noEmit": false,
+		"noImplicitOverride": true,
+		"outDir": "../../lib",
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"target": "ESNext",
+		"tsBuildInfoFile": "../../var/tsbuildinfo.json",
+		"types": ["bootstrap"],
+		"verbatimModuleSyntax": true
+	}
+}