drab 7.0.1 → 7.0.2

package/src/prefetch/index.ts

@@ -0,0 +1,195 @@
+import { Lifecycle, Trigger, type TriggerAttributes } from "../base/index.js";
+
+type Strategy = "hover" | "load" | "visible";
+
+export interface PrefetchAttributes extends TriggerAttributes {
+	/** When to prefetch the url. */
+	strategy?: Strategy;
+
+	/** Prerender on the client with the Speculation Rules API. */
+	prerender?: boolean;
+
+	/** URL to prefetch. */
+	url?: string;
+}
+
+// https://developer.chrome.com/blog/speculation-rules-improvements
+type SpeculationRules = {
+	prerender?: DocumentRule[] | ListRule[];
+	prefetch?: DocumentRule[] | ListRule[];
+};
+
+type Rule = {
+	expects_no_vary_search?: string;
+	referrer_policy?: ReferrerPolicy;
+	requires?: string[];
+};
+
+type DocumentRule = {
+	source: "document";
+	where: WhereCondition;
+	eagerness?: "immediate" | "moderate" | "eager" | "conservative";
+} & Rule;
+
+type ListRule = { source: "list"; urls: string[] } & Rule;
+
+type WhereCondition =
+	| { href_matches: string }
+	| { selector_matches: string }
+	| { and: WhereCondition[] }
+	| { not: WhereCondition }
+	| { or: WhereCondition[] };
+
+/**
+ * The `Prefetch` element can prefetch a url, or enhance the `HTMLAnchorElement` by loading the HTML for a page before it is navigated to. This element speeds up the navigation for multi-page applications (MPAs).
+ *
+ * If you are using a framework that already has a prefetch feature or uses a client side router, it is best to use the framework's feature instead of this element to ensure prefetching is working in accordance with the router.
+ *
+ * ### Attributes
+ *
+ * `strategy`
+ *
+ * Set the `strategy` attribute to specify the when the prefetch will take place.
+ *
+ * - `"hover"` - (default) After `mouseover`, `focus`, or `touchstart` for > 200ms
+ * - `"visible"` - Uses an intersection observer to prefetch when the anchor is within the viewport.
+ * - `"load"` - Immediately prefetches when the element is loaded, use carefully.
+ *
+ * `prerender`
+ *
+ * Use the `prerender` attribute to use the Speculation Rules API when supported to prerender on the client. This allows you to run client side JavaScript in advance instead of only fetching the HTML.
+ *
+ * Browsers that do not support will still use `<link rel="prefetch">` instead.
+ *
+ * [Speculation Rules Reference](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API)
+ *
+ * `url`
+ *
+ * Add a `url` attribute to immediately prefetch a url without having to provide
+ * (or in addition to) `trigger` anchor elements.
+ *
+ * This element can be deprecated once the Speculation Rules API is supported across browsers. The API will be able to prefetch assets in a similar way with the `source: "document"` and `eagerness` features, and will work without JavaScript.
+ */
+export class Prefetch extends Lifecycle(Trigger()) {
+	#prefetchedUrls = new Set<string>();
+
+	constructor() {
+		super();
+	}
+
+	/** When to prefetch the url. */
+	get #strategy() {
+		return this.getAttribute("strategy");
+	}
+
+	/** Prerender with the Speculation Rules API. */
+	get #prerender() {
+		return this.hasAttribute("prerender");
+	}
+
+	/** `url` to prefetch on `mount`.  */
+	get #url() {
+		return this.getAttribute("url");
+	}
+
+	/**
+	 * Appends `<link rel="prefetch">` or `<script type="speculationrules">`
+	 * to the head of the document.
+	 *
+	 * @param options Configuration options.
+	 */
+	prefetch(options: {
+		/** `url` to prefetch. */
+		url: string;
+
+		/**
+		 * Uses the Speculation Rules API when supported to prerender on the client.
+		 */
+		prerender?: boolean;
+	}) {
+		const { url } = options;
+
+		// if not the current page and not already prefetched
+		if (!(url === window.location.href) && !this.#prefetchedUrls.has(url)) {
+			this.#prefetchedUrls.add(url);
+
+			if (
+				HTMLScriptElement.supports &&
+				HTMLScriptElement.supports("speculationrules")
+			) {
+				const rules: SpeculationRules = {
+					// Currently, adding `prefetch` is required to fallback if `prerender` fails.
+					// Possibly will be automatic in the future, in which case it can be removed.
+					// https://github.com/WICG/nav-speculation/issues/162#issuecomment-1977818473
+					prefetch: [{ source: "list", urls: [url] }],
+				};
+
+				if (options.prerender) rules.prerender = rules.prefetch;
+
+				const script = document.createElement("script");
+				script.type = "speculationrules";
+				script.textContent = JSON.stringify(rules);
+				document.head.append(script);
+			} else {
+				const link = document.createElement("link");
+				link.rel = "prefetch";
+				link.as = "document";
+				link.href = url;
+				document.head.append(link);
+			}
+		}
+	}
+
+	override mount() {
+		// immediately prefetch the `url` attribute if it exists
+		if (this.#url)
+			this.prefetch({ url: this.#url, prerender: this.#prerender });
+
+		// prefetch the `trigger` elements
+		const anchors = this.triggers(HTMLAnchorElement);
+		const prerender = this.#prerender;
+		const strategy = this.#strategy;
+
+		let prefetchTimer: NodeJS.Timeout;
+
+		const listener =
+			(delay = 200) =>
+			(e: Event) => {
+				const { href } = e.currentTarget as HTMLAnchorElement;
+				prefetchTimer = setTimeout(
+					() => this.prefetch({ url: href, prerender }),
+					delay,
+				);
+			};
+
+		const reset = () => clearTimeout(prefetchTimer);
+
+		const observer = new IntersectionObserver((entries) => {
+			for (const entry of entries) {
+				if (entry.isIntersecting) {
+					this.prefetch({
+						url: (entry.target as HTMLAnchorElement).href,
+						prerender,
+					});
+				}
+			}
+		});
+
+		for (const anchor of anchors) {
+			if (strategy === "load") {
+				this.prefetch({ url: anchor.href, prerender });
+			} else if (strategy === "visible") {
+				observer.observe(anchor);
+			} else {
+				// "hover" - default
+				anchor.addEventListener("mouseover", listener());
+				anchor.addEventListener("mouseout", reset);
+				anchor.addEventListener("focus", listener());
+				anchor.addEventListener("focusout", reset);
+				// immediately append on touchstart, no delay
+				// passive: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#using_passive_listeners
+				anchor.addEventListener("touchstart", listener(0), { passive: true });
+			}
+		}
+	}
+}

package/src/share/define.ts

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

package/src/share/index.ts

@@ -0,0 +1,99 @@
+import {
+	Announce,
+	Content,
+	type ContentAttributes,
+	Lifecycle,
+	Trigger,
+	type TriggerAttributes,
+} from "../base/index.js";
+
+export type ShareAttributes = TriggerAttributes &
+	ContentAttributes &
+	(
+		| {
+				/** Share URL */
+				url: string;
+
+				/** `ShareData` text (only supported on some targets) */
+				text?: string;
+
+				/** Share title */
+				"share-title"?: string;
+		  }
+		| {
+				/** Text to copy */
+				text: string;
+		  }
+	);
+
+/**
+ * Uses the
+ * [Navigator API](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/share)
+ * to share the `url` if `navigator.share` is supported.
+ *
+ * Otherwise uses the
+ * [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText)
+ * to copy the `url` or `text` provided.
+ *
+ * ### Attributes
+ *
+ * `url`
+ *
+ * URL to share.
+ *
+ * `text`
+ *
+ * Text to copy, or the `ShareData` text if `url` is set (only supported on some targets).
+ *
+ * `share-title`
+ *
+ * `ShareData` title (only supported on some targets).
+ */
+export class Share extends Lifecycle(Trigger(Content(Announce()))) {
+	constructor() {
+		super();
+	}
+
+	// helper since ShareData expects undefined instead of null
+	#attrOrUndefined(name: string) {
+		return this.getAttribute(name) ?? undefined;
+	}
+
+	get #title() {
+		return this.#attrOrUndefined("share-title");
+	}
+
+	get #text() {
+		return this.#attrOrUndefined("text");
+	}
+
+	get #url() {
+		return this.#attrOrUndefined("url");
+	}
+
+	override mount() {
+		this.listener(() => {
+			const data: ShareData = {
+				title: this.#title,
+				text: this.#text,
+				url: this.#url,
+			};
+
+			if (data.url && navigator.canShare && navigator.canShare(data)) {
+				return navigator.share(data).catch((e) => {
+					// catch abort errors when user cancels the share
+					if (!(e instanceof Error) || e.name !== "AbortError") throw e;
+				});
+			}
+
+			const copy = data.url || data.text;
+
+			if (copy) {
+				return navigator.clipboard.writeText(copy).then(() => {
+					this.announce("copied to clipboard");
+					this.swap();
+				});
+			}
+		});
+	}
+}

package/src/tablesort/define.ts

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

package/src/tablesort/index.ts

@@ -0,0 +1,168 @@
+import {
+	Announce,
+	Content,
+	type ContentAttributes,
+	Lifecycle,
+	Trigger,
+	type TriggerAttributes,
+} from "../base/index.js";
+
+export interface TableSortAttributes
+	extends TriggerAttributes,
+		ContentAttributes {}
+
+export interface TableSortTriggerAttributes {
+	"data-type": "string" | "boolean" | "number";
+	"data-value": string;
+}
+
+/**
+ * Wrap a `HTMLTableElement` in the `TableSort` element to have sortable column
+ * headers. Set each `th` that you want to sort to the `trigger`. Set the `tbody`
+ * element to the `content`.
+ *
+ * The values of each cell default to the cell's `textContent`. If you would like to
+ * provide an alternate value than what appears in the cell to sort by instead,
+ * you can set a different value using the `data-value` attribute on the cell.
+ *
+ * The cells will be sorted as `string` by default. If you want to provide a different
+ * datatype `number` or `boolean`, set `data-type="number"` on the corresponding
+ * `th`/`trigger` element. The data will be converted to the specified type before sorting.
+ */
+export class TableSort extends Lifecycle(Trigger(Content(Announce()))) {
+	constructor() {
+		super();
+	}
+
+	get #th() {
+		return this.triggers(HTMLTableCellElement);
+	}
+
+	/**
+	 * Removes `data-asc` or `data-desc` from other triggers then sets the correct attribute on the selected trigger.
+	 *
+	 * @param trigger
+	 * @returns `true` if ascending, `false` if descending
+	 */
+	#setAttributes(trigger: HTMLElement) {
+		const asc = "data-asc";
+		const desc = "data-desc";
+
+		for (const t of this.triggers(HTMLTableCellElement)) {
+			if (t !== trigger) {
+				t.removeAttribute(asc);
+				t.removeAttribute(desc);
+			}
+		}
+
+		if (trigger.hasAttribute(asc)) {
+			trigger.removeAttribute(asc);
+			trigger.setAttribute(desc, "");
+			return false;
+		}
+
+		trigger.removeAttribute(desc);
+		trigger.setAttribute(asc, "");
+
+		return true;
+	}
+
+	override mount() {
+		const tbody = this.content(HTMLTableSectionElement);
+
+		for (const trigger of this.#th) {
+			trigger.tabIndex = 0;
+			trigger.role = "button";
+
+			const listener = () => {
+				const asc = this.#setAttributes(trigger);
+
+				Array.from(tbody.querySelectorAll("tr"))
+					.sort(comparer(trigger, asc))
+					.forEach((tr) => tbody.appendChild(tr));
+
+				this.announce(
+					`sorted table by ${trigger.textContent} in ${asc ? "ascending" : "descending"} order`,
+				);
+			};
+
+			trigger.addEventListener(this.event, listener);
+
+			if (this.event === "click") {
+				trigger.addEventListener("keydown", (e) => {
+					if (e.key === "Enter" || e.key === " ") {
+						e.preventDefault();
+						listener();
+					}
+				});
+			}
+		}
+	}
+}
+
+// adapted from: https://stackoverflow.com/questions/14267781/sorting-html-table-with-javascript/49041392#49041392
+const comparer = (th: HTMLElement, ascending: boolean) => {
+	// this function is returned and used by `sort`
+	const sorter = (a: HTMLTableRowElement, b: HTMLTableRowElement) => {
+		// find the column to sort by using the index of the `th`
+		const columnIndex = Array.from(th.parentNode?.children ?? []).indexOf(th);
+
+		const compare = (aVal: string, bVal: string) => {
+			// default to `string` sorting
+			const dataType = (th.dataset.type ?? "string") as
+				| "string"
+				| "boolean"
+				| "number";
+
+			if (dataType === "string") {
+				const collator = new Intl.Collator();
+				return collator.compare(aVal, bVal);
+			} else if (dataType === "boolean") {
+				return falsyBoolean(aVal) === falsyBoolean(bVal)
+					? 0
+					: falsyBoolean(aVal)
+						? -1
+						: 1;
+			} else {
+				// "number"
+				return Number(aVal) - Number(bVal);
+			}
+		};
+
+		return compare(
+			getValue(ascending ? a : b, columnIndex),
+			getValue(ascending ? b : a, columnIndex),
+		);
+	};
+
+	return sorter;
+};
+
+/**
+ * @param tr the row
+ * @param i index of the `td` to find
+ * @returns a string, the `data-value` attribute, or the `textContent`
+ */
+const getValue = (tr: HTMLTableRowElement, i: number) => {
+	const cell = tr.children[i];
+	if (cell instanceof HTMLElement) {
+		// first look for `data-value` attribute, then use `textContent`
+		return cell.dataset.value ?? cell.textContent ?? "";
+	}
+	return "";
+};
+
+/**
+ * if value is one of these and type is boolean
+ * it should be considered falsy
+ * since actually `Boolean("false") === true`
+ * @param val string pulled from the textContent or attr
+ * @returns a boolean of the provided string
+ */
+const falsyBoolean = (val: string) => {
+	if (["0", "false", "null", "undefined"].includes(val)) {
+		return false;
+	}
+
+	return Boolean(val);
+};

package/src/tabs/define.ts

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

package/src/tabs/index.ts

@@ -0,0 +1,173 @@
+import { Lifecycle, Trigger, type TriggerAttributes } from "../base/index.js";
+
+export interface TabsAttributes extends TriggerAttributes {
+	/** Set to `"vertical"` if tabs are displayed vertically. */
+	orientation?: "horizontal" | "vertical";
+}
+
+/**
+ * Progressively enhance a list of links and content to be tabs by
+ * wrapping with the `Tabs` element. Each `trigger` should be an
+ * `HTMLAnchorElement` with the `href` attribute set to the `id` of the
+ * corresponding tab panel.
+ *
+ * > Tip: Set the `height` of the element the `panel`s are contained in with
+ * > CSS to prevent layout shift when JS is loaded.
+ *
+ * This element is based on
+ * [Chris Ferdinandi's Toggle Tabs](https://gomakethings.com/a-web-component-ui-library-for-people-who-love-html/#toggle-tabs)
+ * design.
+ *
+ * [ARIA Reference](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/)
+ *
+ * - Sets the correct ARIA attributes on each element.
+ * - Supports keyboard navigation based on the `orientation` attribute.
+ * - First tab is selected by default if no `aria-selected="true"` attribute is
+ * found on another tab.
+ * - `tablist` is calculated based on the deepest common parent of the tabs,
+ * throws an error if not found.
+ *
+ * ### Attributes
+ *
+ * `orientation`
+ *
+ * Set `orientation="vertical"` if the `tablist` element is displayed vertically.
+ */
+export class Tabs extends Lifecycle(Trigger()) {
+	/** Supported keys for keyboard navigation. */
+	#keys = ["ArrowRight", "ArrowDown", "ArrowLeft", "ArrowUp", "Home", "End"];
+
+	/** Currently selected tab. */
+	#selected: { tab?: HTMLAnchorElement; index: number } = { index: 0 };
+
+	constructor() {
+		super();
+	}
+
+	/** User provided orientation of the `tablist`. */
+	get #orientation() {
+		return this.getAttribute("orientation") ?? "horizontal";
+	}
+
+	get #tabs() {
+		return this.triggers(HTMLAnchorElement);
+	}
+
+	/**
+	 * @param tab
+	 * @returns The ancestors of the tab up to `this`.
+	 */
+	#ancestors(tab?: HTMLElement) {
+		const ancestors = new Set<HTMLElement>();
+
+		let current: HTMLElement | null | undefined = tab;
+		while ((current = current?.parentElement) && current !== this) {
+			ancestors.add(current);
+		}
+
+		return ancestors;
+	}
+
+	/** A map of each `tab` and its corresponding `panel`. */
+	get #map() {
+		const map = new Map<HTMLAnchorElement, HTMLElement>();
+
+		for (const tab of this.#tabs) {
+			const panel = this.querySelector(tab.hash);
+			if (!(panel instanceof HTMLElement))
+				throw new Error(`Tabs: No HTMLElement with ID of ${tab.hash} found.`);
+
+			map.set(tab, panel);
+		}
+
+		return map;
+	}
+
+	override mount() {
+		// create tablist
+		const [first, ...rest] = this.#tabs;
+		let common = this.#ancestors(first);
+		for (let i = 0; i < rest.length; i++) {
+			common = common.intersection(this.#ancestors(rest[i]));
+		}
+		const [tablist] = common;
+		if (!tablist)
+			throw new Error("Tabs: No common parent element found for triggers.");
+		tablist.role = "tablist";
+		tablist.ariaOrientation = this.#orientation;
+
+		// enhance tabs/panels
+		let index = 0;
+		for (const [tab, panel] of this.#map) {
+			tab.role = "tab";
+			tab.id = `tab-${panel.id}`;
+			tab.setAttribute("aria-controls", panel.id);
+			if (tab.ariaSelected) this.#selected = { tab, index };
+
+			panel.role = "tabpanel";
+			panel.setAttribute("aria-labelledby", tab.id);
+
+			tab.addEventListener(this.event, (e) => {
+				e.preventDefault();
+
+				for (const [t, p] of this.#map) {
+					if (t === tab) {
+						// show current
+						t.ariaSelected = "true";
+						t.tabIndex = 0;
+						p.hidden = false;
+					} else {
+						// hide others
+						t.ariaSelected = "false";
+						t.tabIndex = -1;
+						p.hidden = true;
+					}
+				}
+			});
+
+			index++;
+		}
+
+		// fallback to first
+		if (!this.#selected.tab) this.#selected.tab = this.#tabs[0];
+
+		// select the current tab
+		this.#selected.tab?.click();
+
+		// handle keyboard navigation
+		this.addEventListener("keydown", (e) => {
+			const i = this.#keys.indexOf(e.key);
+			if (i === -1) return;
+
+			const previousIndex = this.#selected.index;
+			const vertical = this.#orientation === "vertical";
+
+			if (
+				((!vertical && i === 0) || (vertical && i === 1)) &&
+				this.#tabs[this.#selected.index + 1]
+			) {
+				// next
+				this.#selected.tab = this.#tabs[++this.#selected.index];
+			} else if (
+				((!vertical && i === 2) || (vertical && i === 3)) &&
+				this.#tabs[this.#selected.index - 1]
+			) {
+				// previous
+				this.#selected.tab = this.#tabs[--this.#selected.index];
+			} else if (i === 4) {
+				// home
+				this.#selected = { tab: this.#tabs[0], index: 0 };
+			} else if (i === 5) {
+				// end
+				const index = this.#tabs.length - 1;
+				this.#selected = { tab: this.#tabs[index], index };
+			}
+
+			if (this.#selected.index === previousIndex) return;
+
+			e.preventDefault();
+			this.#selected.tab?.click();
+			this.#selected.tab?.focus();
+		});
+	}
+}

package/src/types/index.ts

@@ -0,0 +1,39 @@
+import type { AnnouncerAttributes } from "../announcer/index.js";
+import type { ContextMenuAttributes } from "../contextmenu/index.js";
+import type { DialogAttributes } from "../dialog/index.js";
+import type { EditorAttributes } from "../editor/index.js";
+import type { FullscreenAttributes } from "../fullscreen/index.js";
+import type { IntersectAttributes } from "../intersect/index.js";
+import type { PrefetchAttributes } from "../prefetch/index.js";
+import type { ShareAttributes } from "../share/index.js";
+import type { TableSortAttributes } from "../tablesort/index.js";
+import type { TabsAttributes } from "../tabs/index.js";
+import type { WakeLockAttributes } from "../wakelock/index.js";
+
+export interface Attributes {
+	announcer: AnnouncerAttributes;
+	contextmenu: ContextMenuAttributes;
+	dialog: DialogAttributes;
+	editor: EditorAttributes;
+	fullscreen: FullscreenAttributes;
+	intersect: IntersectAttributes;
+	prefetch: PrefetchAttributes;
+	share: ShareAttributes;
+	tablesort: TableSortAttributes;
+	tabs: TabsAttributes;
+	wakelock: WakeLockAttributes;
+}
+
+type Prefixed<
+	Prefix extends string,
+	GlobalAttributes,
+	ElementAttributes extends Record<string, any>,
+> = {
+	[K in keyof ElementAttributes as `${Prefix}-${Extract<K, string>}`]: ElementAttributes[K] &
+		GlobalAttributes;
+};
+
+export type Elements<
+	GlobalAttributes,
+	Prefix extends string = "drab",
+> = Prefixed<Prefix, GlobalAttributes, Attributes>;

package/src/util/define.ts

@@ -0,0 +1,10 @@
+/**
+ * Define a custom element to the registry. Checks if the element is
+ * defined and then names the element.
+ *
+ * @param name name of the custom element
+ * @param Constructor custom element constructor
+ */
+export const define = (name: string, Constructor: CustomElementConstructor) => {
+	if (!customElements.get(name)) customElements.define(name, Constructor);
+};