drab 7.0.1 → 7.0.2

package/src/base/index.ts

@@ -0,0 +1,290 @@
+import { Announcer } from "../announcer/index.js";
+import { validate } from "../util/validate.js";
+
+export interface TriggerAttributes {
+	trigger?: string;
+}
+
+export interface ContentAttributes {
+	content?: string;
+	swap?: string;
+}
+
+export type Constructor<T> = new (...args: any[]) => T;
+
+export const Lifecycle = <T extends Constructor<HTMLElement>>(
+	Super = HTMLElement as T,
+) =>
+	class Lifecycle extends Super {
+		/** To clean up event listeners added to `document` when the element is removed. */
+		#listenerController = new AbortController();
+
+		constructor(...args: any[]) {
+			super(...args);
+		}
+
+		/**
+		 * Wrapper around `addEventListener` that ensures when the element is
+		 * removed from the DOM, these event listeners are cleaned up.
+		 *
+		 * @param type Event listener type - ex: `"keydown"`
+		 * @param listener Listener to add to the target.
+		 * @param target Event target to add the listener to - defaults to `document.body`.
+		 * @param options Other options sans `signal`.
+		 */
+		safeListener<T extends keyof HTMLElementEventMap>(
+			type: T,
+			listener: (this: HTMLElement, event: HTMLElementEventMap[T]) => any,
+			element?: HTMLElement,
+			options?: AddEventListenerOptions,
+		): void;
+		safeListener<T extends keyof DocumentEventMap>(
+			type: T,
+			listener: (this: Document, event: DocumentEventMap[T]) => any,
+			document: Document,
+			options?: AddEventListenerOptions,
+		): void;
+		safeListener<T extends keyof WindowEventMap>(
+			type: T,
+			listener: (this: Window, event: WindowEventMap[T]) => any,
+			window: Window,
+			options?: AddEventListenerOptions,
+		): void;
+		safeListener(
+			type: string,
+			listener: EventListenerOrEventListenerObject,
+			target: EventTarget = document.body,
+			options: AddEventListenerOptions = {},
+		) {
+			options.signal = this.#listenerController.signal;
+			target.addEventListener(type, listener, options);
+		}
+
+		/**
+		 * Passed into `queueMicrotask` in `connectedCallback`.
+		 * It is overridden in each component that needs to run `connectedCallback`.
+		 *
+		 * The reason for this is to make these elements work better with frameworks like Svelte.
+		 * For SSR this isn't necessary, but when client side rendering, the HTML within the
+		 * custom element isn't available before `connectedCallback` is called. By waiting until
+		 * the next microtask, the HTML content is available---then for example, listeners can
+		 * be attached to elements inside.
+		 */
+		mount() {}
+
+		/** Called when custom element is added to the page. */
+		connectedCallback() {
+			queueMicrotask(() => this.mount());
+		}
+
+		/**
+		 * Passed into `disconnectedCallback`, since `Base` needs to run `disconnectedCallback` as well. It is overridden in each element that needs to run `disconnectedCallback`.
+		 */
+		destroy() {}
+
+		/** Called when custom element is removed from the page. */
+		disconnectedCallback() {
+			this.destroy();
+			this.#listenerController.abort();
+		}
+	};
+
+type Listener<T extends keyof HTMLElementEventMap> = (
+	this: HTMLElement,
+	e: HTMLElementEventMap[T],
+) => any;
+
+/**
+ * By default, `trigger`s are selected via the `data-trigger` attribute.
+ * Alternatively, you can set the `trigger` attribute to a CSS selector to
+ * change the default selector from `[data-trigger]` to a selector of your
+ * choosing. This can be useful if you have multiple elements within one another.
+ *
+ * Each element can have multiple `trigger`s.
+ */
+export const Trigger = <T extends Constructor<HTMLElement>>(
+	Super = HTMLElement as T,
+) =>
+	class Trigger extends Super {
+		constructor(...args: any[]) {
+			super(...args);
+		}
+
+		/**
+		 * Event for the `trigger` to execute.
+		 *
+		 * For example, set to `"mouseover"` to execute the event when the user hovers the mouse over the `trigger`, instead of when they click it.
+		 *
+		 * @default "click"
+		 */
+		get event(): keyof HTMLElementEventMap {
+			return (
+				(this.getAttribute("event") as keyof HTMLElementEventMap) ?? "click"
+			);
+		}
+
+		set event(value) {
+			this.setAttribute("event", value);
+		}
+
+		/**
+		 * @param instance The instance of the desired element to validate against,
+		 * ex: `HTMLButtonElement`. Defaults to `HTMLElement`.
+		 * @returns All of the elements that match the `trigger` selector.
+		 * @default this.querySelectorAll("[data-trigger]")
+		 */
+		triggers<T extends HTMLElement>(instance: Constructor<T>): NodeListOf<T>;
+		triggers(): NodeListOf<HTMLElement>;
+		triggers(instance = HTMLElement) {
+			const triggers = this.querySelectorAll(
+				this.getAttribute("trigger") ?? "[data-trigger]",
+			);
+
+			for (const trigger of triggers) validate(trigger, instance);
+
+			return triggers;
+		}
+
+		/**
+		 * @param listener Listener to attach to all of the `trigger` elements.
+		 * @param options
+		 */
+		listener<T extends keyof HTMLElementEventMap>(
+			listener: Listener<T>,
+			options?: AddEventListenerOptions,
+		): void;
+		/**
+		 * @param type Event type.
+		 * @param listener Listener to attach to all of the `trigger` elements.
+		 * @param options
+		 */
+		listener<T extends keyof HTMLElementEventMap>(
+			type: T,
+			listener: Listener<T>,
+			options?: AddEventListenerOptions,
+		): void;
+		listener<T extends keyof HTMLElementEventMap>(
+			listenerOrType: Listener<T> | T,
+			listenerOrOptions?: Listener<T> | AddEventListenerOptions,
+			optionsMaybe?: AddEventListenerOptions,
+		): void {
+			let type: keyof HTMLElementEventMap;
+			let listener: Listener<any>;
+			let options: AddEventListenerOptions | undefined;
+
+			if (typeof listenerOrType === "function") {
+				// (listener, options?)
+				type = this.event;
+				listener = listenerOrType;
+				options = listenerOrOptions as AddEventListenerOptions;
+			} else {
+				// (type, listener, options?)
+				type = listenerOrType;
+				listener = listenerOrOptions as Listener<T>;
+				options = optionsMaybe;
+			}
+
+			for (const trigger of this.triggers()) {
+				trigger.addEventListener(type, listener, options);
+			}
+		}
+	};
+
+/**
+ * By default, `content` is selected via the `data-content` attribute.
+ * Alternatively, you can set the `trigger` to a CSS selector to change
+ * the default selector from `[data-trigger]` to a selector of your choosing.
+ * This can be useful if you have multiple elements within one another.
+ *
+ * Each element can only have one `content`.
+ */
+export const Content = <T extends Constructor<HTMLElement>>(
+	Super = HTMLElement as T,
+) =>
+	class Content extends Super {
+		constructor(...args: any[]) {
+			super(...args);
+		}
+
+		/**
+		 * @param instance The instance of the desired element to validate against,
+		 * ex: `HTMLDialogElement`. Defaults to `HTMLElement`.
+		 * @returns The element that matches the `content` selector.
+		 * @default this.querySelector("[data-content]")
+		 */
+		content<T extends HTMLElement>(instance: Constructor<T>): T;
+		content(): HTMLElement;
+		content(instance = HTMLElement) {
+			return validate(
+				this.querySelector(this.getAttribute("content") ?? "[data-content]"),
+				instance,
+			);
+		}
+
+		/**
+		 * Finds the `HTMLElement | HTMLTemplateElement` via the `swap` selector and
+		 * swaps `this.content()` with the content of the element found.
+		 *
+		 * @param revert Wait time (ms) before swapping back, set to `false` to not revert.
+		 * default: `800`
+		 */
+		swap(revert: number | false = 800) {
+			/** The swap element, used to hold the replacement contents. */
+			const swapTarget = this.querySelector(
+				this.getAttribute("swap") ?? "[data-swap]",
+			);
+
+			if (swapTarget) {
+				/** A copy of the content currently in `this.getContent()`. */
+				const currentContent = this.content().childNodes;
+
+				/**
+				 * The contents of the swap element, set based on whether the
+				 * swap is a `template` or not.
+				 */
+				const placeholder: Node[] = [];
+
+				// Set the placeholder with the `swap` content, then replace the
+				// swap content with the `currentContent`
+				if (swapTarget instanceof HTMLTemplateElement) {
+					// use `content` since it's a `template` element
+					placeholder.push(swapTarget.content.cloneNode(true));
+					swapTarget.content.replaceChildren(...currentContent);
+				} else {
+					// not a `template`, replace children directly
+					placeholder.push(...swapTarget.childNodes);
+					swapTarget.replaceChildren(...currentContent);
+				}
+
+				// finally, set the content to the contents of the placeholder
+				this.content().replaceChildren(...placeholder);
+
+				if (revert) {
+					// wait and then run again to swap back
+					setTimeout(() => this.swap(0), revert);
+				}
+			}
+		}
+	};
+
+export const Announce = <T extends Constructor<HTMLElement>>(
+	Super = HTMLElement as T,
+) =>
+	class Announce extends Super {
+		/**
+		 * A single `Announcer` element to share between all drab elements to announce
+		 * interactive changes.
+		 */
+		static #announcer = Announcer.init();
+
+		constructor(...args: any[]) {
+			super(...args);
+		}
+
+		/**
+		 * @param message message to announce to screen readers
+		 */
+		announce(message: string) {
+			Announce.#announcer.announce(message);
+		}
+	};

package/src/contextmenu/define.ts

@@ -0,0 +1,4 @@
+import { define } from "../util/define.js";
+import { ContextMenu } from "./index.js";
+
+define("drab-contextmenu", ContextMenu);

package/src/contextmenu/index.ts

@@ -0,0 +1,95 @@
+import {
+	Content,
+	type ContentAttributes,
+	Lifecycle,
+	Trigger,
+	type TriggerAttributes,
+} from "../base/index.js";
+
+export interface ContextMenuAttributes
+	extends TriggerAttributes,
+		ContentAttributes {}
+
+/**
+ * Displays content when the `trigger` element is right clicked, or long pressed on mobile.
+ */
+export class ContextMenu extends Lifecycle(Trigger(Content())) {
+	/** Tracks the long press duration on mobile. */
+	#touchTimer: NodeJS.Timeout | undefined;
+
+	constructor() {
+		super();
+	}
+
+	/** Sets the context menu's `style.left` and `style.top` position. */
+	set #coordinates(value: { x: number; y: number }) {
+		this.content().style.left = `${value.x}px`;
+		this.content().style.top = `${value.y}px`;
+	}
+
+	show(e: MouseEvent | TouchEvent) {
+		// find coordinates of the click
+		const scrollY = window.scrollY;
+		const scrollX = window.scrollX;
+
+		const clientX =
+			e instanceof MouseEvent ? e.clientX : (e.touches[0]?.clientX ?? 0);
+		const clientY =
+			e instanceof MouseEvent ? e.clientY : (e.touches[0]?.clientY ?? 0);
+
+		let x = clientX + scrollX;
+		let y = clientY + scrollY;
+
+		this.content().style.position = "absolute";
+		this.content().setAttribute("data-open", "");
+
+		const offsetWidth = this.content().offsetWidth + 24;
+		const offsetHeight = this.content().offsetHeight + 6;
+		const innerWidth = window.innerWidth;
+		const innerHeight = window.innerHeight;
+
+		// ensure menu is within view
+		if (x + offsetWidth > scrollX + innerWidth) {
+			x = scrollX + innerWidth - offsetWidth;
+		}
+		if (y + offsetHeight > scrollY + innerHeight) {
+			y = scrollY + innerHeight - offsetHeight;
+		}
+
+		this.#coordinates = { x, y };
+	}
+
+	hide() {
+		this.content().removeAttribute("data-open");
+	}
+
+	override mount() {
+		// mouse
+		this.listener("contextmenu", (e) => {
+			e.preventDefault();
+			this.show(e);
+		});
+
+		this.safeListener("click", () => this.hide());
+
+		// touch
+		this.listener(
+			"touchstart",
+			(e) => {
+				this.#touchTimer = setTimeout(() => {
+					this.show(e);
+				}, 800);
+			},
+			{ passive: true },
+		);
+
+		const resetTimer = () => clearTimeout(this.#touchTimer);
+		this.listener("touchend", resetTimer, { passive: true });
+		this.listener("touchcancel", resetTimer, { passive: true });
+
+		// keyboard
+		this.safeListener("keydown", (e) => {
+			if (e.key === "Escape") this.hide();
+		});
+	}
+}

package/src/define.ts

@@ -0,0 +1,11 @@
+import "./announcer/define.js";
+import "./contextmenu/define.js";
+import "./dialog/define.js";
+import "./editor/define.js";
+import "./fullscreen/define.js";
+import "./intersect/define.js";
+import "./prefetch/define.js";
+import "./share/define.js";
+import "./tablesort/define.js";
+import "./tabs/define.js";
+import "./wakelock/define.js";

package/src/dialog/define.ts

@@ -0,0 +1,4 @@
+import { define } from "../util/define.js";
+import { Dialog } from "./index.js";
+
+define("drab-dialog", Dialog);

package/src/dialog/index.ts

@@ -0,0 +1,120 @@
+import {
+	Content,
+	type ContentAttributes,
+	Lifecycle,
+	Trigger,
+	type TriggerAttributes,
+} from "../base/index.js";
+
+export interface DialogAttributes extends TriggerAttributes, ContentAttributes {
+	/** Close the dialog when clicked outside. */
+	"click-outside-close"?: boolean;
+
+	/** Remove scroll from the body when dialog is open. */
+	"remove-body-scroll"?: boolean;
+}
+
+/**
+ * Provides triggers for the `HTMLDialogElement`.
+ *
+ * ### Attributes
+ *
+ * `click-outside-close`
+ *
+ * By default, the `HTMLDialogElement` doesn't close if the user clicks outside of it.
+ * Add a `click-outside-close` attribute to close when the user clicks outside.
+ *
+ * If the dialog covers the full viewport and this attribute is present, the first child
+ * of the dialog will be assumed to be the content of the dialog and the dialog will close
+ * if there is a click outside of the first child element.
+ *
+ * `remove-body-scroll`
+ *
+ * Add the `remove-body-scroll` attribute to remove the scroll from `document.body` when the dialog
+ * is open.
+ */
+export class Dialog extends Lifecycle(Trigger(Content())) {
+	constructor() {
+		super();
+	}
+
+	/** The `HTMLDialogElement` within the element. */
+	get #dialog() {
+		return this.content(HTMLDialogElement);
+	}
+
+	get #removeBodyScroll() {
+		return this.hasAttribute("remove-body-scroll");
+	}
+
+	get #clickOutsideClose() {
+		return this.hasAttribute("click-outside-close");
+	}
+
+	get #scrollbarWidth() {
+		return window.innerWidth - document.documentElement.clientWidth;
+	}
+
+	/** Remove scroll from the body when open with the `remove-body-scroll` attribute. */
+	#toggleBodyScroll(show: boolean) {
+		if (this.#removeBodyScroll) {
+			document.documentElement.style.scrollbarGutter = "stable";
+			document.body.style.overflow = show ? "hidden" : "";
+		}
+	}
+
+	/** Wraps `HTMLDialogElement.showModal()`. */
+	show() {
+		this.#dialog.showModal();
+		this.#toggleBodyScroll(true);
+	}
+
+	/** Wraps `HTMLDialogElement.close()`. */
+	close() {
+		this.#toggleBodyScroll(false);
+		this.#dialog.close();
+	}
+
+	/** `show` or `close` depending on the dialog's `open` attribute. */
+	toggle() {
+		if (this.#dialog.open) this.close();
+		else this.show();
+	}
+
+	override mount() {
+		this.listener(() => this.toggle());
+
+		this.safeListener("keydown", (e) => {
+			if (e.key === "Escape" && this.#dialog.open) {
+				e.preventDefault();
+				this.close();
+			}
+		});
+
+		if (this.#clickOutsideClose) {
+			// https://blog.webdevsimplified.com/2023-04/html-dialog/#close-on-outside-click
+			this.#dialog.addEventListener("click", (e) => {
+				let rect = this.#dialog.getBoundingClientRect();
+
+				// If dialog covers full viewport, use first child element for hit testing
+				// Example: https://picocss.com/docs/modal
+				if (
+					Math.abs(rect.width - window.innerWidth) <= this.#scrollbarWidth && // 5px tolerance for rounding issues
+					Math.abs(rect.height - window.innerHeight) <= 0 &&
+					this.#dialog.firstElementChild
+				) {
+					rect = this.#dialog.firstElementChild.getBoundingClientRect();
+				}
+
+				if (
+					e.clientX < rect.left ||
+					e.clientX > rect.right ||
+					e.clientY < rect.top ||
+					e.clientY > rect.bottom
+				) {
+					this.close();
+				}
+			});
+		}
+	}
+}

package/src/editor/define.ts

@@ -0,0 +1,4 @@
+import { define } from "../util/define.js";
+import { Editor } from "./index.js";
+
+define("drab-editor", Editor);