@oscarpalmer/toretto 0.46.0 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/toretto",
-	"version": "0.46.0",
+	"version": "0.47.0",
 	"description": "A collection of badass DOM utilities.",
 	"keywords": [
 		"dom",
@@ -30,6 +30,10 @@
 			"types": "./dist/index.d.mts",
 			"default": "./dist/index.mjs"
 		},
+		"./aria": {
+			"types": "./dist/aria.d.mts",
+			"default": "./dist/aria.mjs"
+		},
 		"./attribute": {
 			"types": "./dist/attribute/index.d.mts",
 			"default": "./dist/attribute/index.mjs"
@@ -86,11 +90,11 @@
 		"test:leak": "npx vp test run --detect-async-leaks --coverage"
 	},
 	"dependencies": {
-		"@oscarpalmer/atoms": "^0.187.2"
+		"@oscarpalmer/atoms": "^0.188.1"
 	},
 	"devDependencies": {
-		"@oxlint/plugins": "^1.67",
-		"@types/node": "^25.9",
+		"@oxlint/plugins": "^1.73",
+		"@types/node": "^26.1",
 		"@vitest/coverage-istanbul": "^4.1",
 		"jsdom": "^29.1",
 		"tsdown": "^0.22",

package/src/aria.ts

@@ -0,0 +1,166 @@
+import {setElementValues, updateElementValue} from './internal/element-value';
+import type {AriaAttribute, AriaAttributeUnprefixed, AriaRole} from './models';
+
+// #region Types
+
+type AnyAriaAttribute = AriaAttribute | AriaAttributeUnprefixed;
+
+type AriaAttributeItem = {
+	name: AnyAriaAttribute;
+	value?: string;
+};
+
+// #endregion
+
+// #region Functions
+
+/**
+ * Get the value of a specific _ARIA_ attribute from an element
+ *
+ * @param element Element to get _ARIA_ attribute from
+ * @param name _ARIA_ name
+ * @returns _ARIA_ value _(or `undefined`)_
+ */
+export function getAria(element: Element, attribute: AnyAriaAttribute): string | undefined;
+
+/**
+ * Get specific _ARIA_ attributes from an element
+ *
+ * @param element Element to get _ARIA_ attributes from
+ * @param names _ARIA_ attribute names
+ * @returns Object of named _ARIA_ attributes
+ */
+export function getAria<Attribute extends AnyAriaAttribute>(
+	element: Element,
+	attributes: Attribute[],
+): Record<Attribute, string | undefined>;
+
+export function getAria(element: Element, value: string | string[]): unknown {
+	if (!(element instanceof Element)) {
+		return Array.isArray(value) ? {} : undefined;
+	}
+
+	if (!Array.isArray(value)) {
+		return typeof value === 'string' ? getAriaValue(element, value) : undefined;
+	}
+
+	const arias = {} as Record<string, string | undefined>;
+
+	const {length} = value;
+
+	for (let index = 0; index < length; index += 1) {
+		const attribute = value[index];
+
+		if (typeof attribute === 'string') {
+			arias[attribute.replace(ATTRIBUTE_ARIA_PREFIX, '')] = getAriaValue(element, attribute);
+		}
+	}
+
+	return arias;
+}
+
+function getAriaValue(element: Element, attribute: string): string | undefined {
+	return element.getAttribute(getName(attribute)) ?? undefined;
+}
+
+function getName(value: string): string {
+	return EXPRESSION_ARIA_PREFIX.test(value) ? value : `${ATTRIBUTE_ARIA_PREFIX}${value}`;
+}
+
+/**
+ * Get the role of an element
+ *
+ * @param element Element to get role from
+ * @returns Element role _(or `undefined`)_
+ */
+export function getRole(element: Element): unknown {
+	if (element instanceof Element) {
+		return element.getAttribute('role') ?? undefined;
+	}
+}
+
+/**
+ * Set an _ARIA_ attribute on an element
+ *
+ * _(Or remove it, if value is `null` or `undefined`)_
+ *
+ * @param element Element for _ARIA_ attribute
+ * @param attribute _ARIA_ attribute to set
+ * @param value _ARIA_ attribute value
+ */
+export function setAria(element: Element, attribute: AnyAriaAttribute, value?: string): void;
+
+/**
+ * Set one or more _ARIA_ attributes on an element
+ *
+ * _(Or remove them, if their value is `null` or `undefined`)_
+ *
+ * @param element Element for _ARIA_ attributes
+ * @param attributes _ARIA_ attributes to set
+ */
+export function setAria(element: Element, attributes: AriaAttributeItem[]): void;
+
+/**
+ * Set one or more _ARIA_ attributes on an element
+ *
+ * _(Or remove them, if their value is `null` or `undefined`)_
+ *
+ * @param element Element for _ARIA_ attributes
+ * @param attributes _ARIA_ attributes to set
+ */
+export function setAria(
+	element: Element,
+	attributes: Partial<Record<AnyAriaAttribute, unknown>>,
+): void;
+
+export function setAria(
+	element: Element,
+	first: AnyAriaAttribute | AriaAttributeItem[] | Partial<Record<AnyAriaAttribute, unknown>>,
+	second?: unknown,
+): void {
+	setElementValues(element, first, second, null, updateAriaAttribute);
+}
+
+/**
+ * Set the role of an element
+ *
+ * @param element Element for role
+ * @param role Role to set _(or `undefined` to remove it)_
+ */
+export function setRole(element: Element, role?: AriaRole): void {
+	if (!(element instanceof Element)) {
+		return;
+	}
+
+	if (typeof role === 'string') {
+		element.setAttribute('role', role);
+	} else {
+		element.removeAttribute('role');
+	}
+}
+
+function updateAriaAttribute(element: Element, key: string, value: unknown): void {
+	updateElementValue(
+		element,
+		getName(key),
+		value,
+		// Using `.call` in `updateElementValue`
+		// oxlint-disable-next-line typescript/unbound-method
+		element.setAttribute,
+		// Using `.call` in `updateElementValue`
+		// oxlint-disable-next-line typescript/unbound-method
+		element.removeAttribute,
+		false,
+		false,
+	);
+}
+
+// #endregion
+
+// #region Variables
+
+const ATTRIBUTE_ARIA_PREFIX = 'aria-';
+
+const EXPRESSION_ARIA_PREFIX = /^aria-/i;
+
+// #endregion

package/src/attribute/get.attribute.ts

@@ -1,6 +1,5 @@
 import {kebabCase} from '@oscarpalmer/atoms/string/case';
 import {getAttributeValue} from '../internal/get-value';
-import {isHTMLOrSVGElement} from '../internal/is';
 
 // #region Types
 
@@ -12,6 +11,7 @@ type DataPrefixedName = `data-${string}`;
 
 /**
  * Get the value of a specific attribute from an element
+ *
  * @param element Element to get attribute from
  * @param name Attribute name
  * @param parse Parse value? _(defaults to `true`)_
@@ -29,7 +29,7 @@ export function getAttribute(element: Element, name: DataPrefixedName, parse?: b
 export function getAttribute(element: Element, name: string): unknown;
 
 export function getAttribute(element: Element, name: string, parseValues?: boolean): unknown {
-	if (isHTMLOrSVGElement(element) && typeof name === 'string') {
+	if (element instanceof Element && typeof name === 'string') {
 		return getAttributeValue(element, kebabCase(name), parseValues !== false);
 	}
 }
@@ -49,7 +49,7 @@ export function getAttributes<Key extends string>(
 ): Record<Key, unknown> {
 	const attributes: Record<string, unknown> = {};
 
-	if (!(isHTMLOrSVGElement(element) && Array.isArray(names))) {
+	if (!(element instanceof Element && Array.isArray(names))) {
 		return attributes;
 	}
 

package/src/create.ts

@@ -1,7 +1,7 @@
 import type {Primitive} from '@oscarpalmer/atoms/models';
 import {setAttributes} from './attribute';
-import {setStyles} from './style';
 import {setProperties} from './property';
+import {setStyles} from './style';
 
 // #region Types
 
@@ -16,7 +16,7 @@ type Styles = Partial<Record<keyof CSSStyleDeclaration, unknown>>;
 // #region Functions
 
 /**
- * Creates an HTML element with the specified tag name together with optional properties, attributes, and styles
+ * Creates an _HTML_ element with the specified tag name together with optional properties, attributes, and styles
  *
  * @param tag Tag name
  * @param properties Element properties
@@ -32,7 +32,7 @@ export function createElement<TagName extends keyof HTMLElementTagNameMap>(
 ): HTMLElementTagNameMap[TagName];
 
 /**
- * Creates an HTML element with the specified tag name together with optional properties, attributes, and styles
+ * Creates an _HTML_ element with the specified tag name together with optional properties, attributes, and styles
  *
  * @param tag Tag name
  * @param properties Element properties

package/src/data.ts

@@ -3,7 +3,6 @@ import {parse} from '@oscarpalmer/atoms/string';
 import {camelCase, kebabCase} from '@oscarpalmer/atoms/string/case';
 import {setElementValues, updateElementValue} from './internal/element-value';
 import {EXPRESSION_DATA_PREFIX} from './internal/get-value';
-import {isHTMLOrSVGElement} from './internal/is';
 
 // #region Functions
 
@@ -32,14 +31,14 @@ export function getData<Key extends string>(
 ): Record<Key, unknown>;
 
 export function getData(element: Element, keys: string | string[], parseValues?: boolean): unknown {
-	if (!isHTMLOrSVGElement(element)) {
+	if (!(element instanceof Element)) {
 		return;
 	}
 
 	const noParse = parseValues === false;
 
 	if (typeof keys === 'string') {
-		const value = element.dataset[camelCase(keys)];
+		const value = (element as HTMLElement).dataset[camelCase(keys)];
 
 		if (value === undefined) {
 			return;
@@ -54,7 +53,7 @@ export function getData(element: Element, keys: string | string[], parseValues?:
 
 	for (let index = 0; index < length; index += 1) {
 		const key = keys[index];
-		const value = element.dataset[camelCase(key)];
+		const value = (element as HTMLElement).dataset[camelCase(key)];
 
 		if (value == null) {
 			data[key] = undefined;
@@ -96,9 +95,11 @@ function updateDataAttribute(element: Element, key: string, value: unknown): voi
 		element,
 		getName(key),
 		value,
-		// oxlint-disable-next-line typescript/unbound-method: using .call in `updateElementValue`
+		// Using `.call` in `updateElementValue`
+		// oxlint-disable-next-line typescript/unbound-method
 		element.setAttribute,
-		// oxlint-disable-next-line typescript/unbound-method: using .call in `updateElementValue`
+		// Using `.call` in `updateElementValue`
+		// oxlint-disable-next-line typescript/unbound-method
 		element.removeAttribute,
 		false,
 		true,

package/src/event/delegation.ts

@@ -43,7 +43,7 @@ export function addDelegatedListener(
 }
 
 function delegatedEventHandler(this: boolean, event: Event): void {
-	const key = `${EVENT_PREFIX}${event.type}${this ? EVENT_SUFFIX_PASSIVE : EVENT_SUFFIX_ACTIVE}`;
+	const key = `@${event.type}${this ? EVENT_SUFFIX_PASSIVE : EVENT_SUFFIX_ACTIVE}`;
 
 	const items = event.composedPath();
 	const {length} = items;
@@ -51,7 +51,8 @@ function delegatedEventHandler(this: boolean, event: Event): void {
 	let cancelled = false;
 	let target = items[0];
 
-	// oxlint-disable-next-line typescript/unbound-method: using `.call` to ensure correct `this` context
+	// Using `.call` to ensure correct `this` context
+	// oxlint-disable-next-line typescript/unbound-method
 	const originalStopPropagation = event.stopPropagation;
 
 	event.stopPropagation = function () {
@@ -108,7 +109,7 @@ export function getDelegatedName(
 		!options.once &&
 		options.signal == null
 	) {
-		return `${EVENT_PREFIX}${type}${options.passive ? EVENT_SUFFIX_PASSIVE : EVENT_SUFFIX_ACTIVE}`;
+		return `@${type}${options.passive ? EVENT_SUFFIX_PASSIVE : EVENT_SUFFIX_ACTIVE}`;
 	}
 }
 
@@ -138,13 +139,11 @@ export function removeDelegatedListener(
 
 const DELEGATED = new Set<string>();
 
-const EVENT_PREFIX = '@';
-
 const EVENT_SUFFIX_ACTIVE = ':active';
 
 const EVENT_SUFFIX_PASSIVE = ':passive';
 
-const EVENT_TYPES: Set<string> = new Set([
+const EVENT_TYPES = new Set([
 	'beforeinput',
 	'click',
 	'dblclick',

package/src/event/index.ts

@@ -35,7 +35,7 @@ function createDispatchOptions(options: EventInit): EventInit {
 function createEvent(type: string, options?: CustomEventInit): Event {
 	const hasOptions = isPlainObject(options);
 
-	if (hasOptions && PROPERTY_DETAIL in (options as CustomEventInit)) {
+	if (hasOptions && 'detail' in (options as CustomEventInit)) {
 		return new CustomEvent(type, {
 			...createDispatchOptions(options as CustomEventInit),
 			detail: options?.detail,
@@ -231,9 +231,3 @@ export function on(
 }
 
 // #endregion
-
-// #region Variables
-
-const PROPERTY_DETAIL = 'detail';
-
-// #endregion

package/src/html/index.ts

@@ -5,9 +5,9 @@ import {sanitizeNodes} from './sanitize';
 
 // #region Types
 
-type HtmlOptions = {
+export type HtmlOptions = {
 	/**
-	 * Cache template element for the HTML string? _(defaults to `true`)_
+	 * Cache template element for the _HTML_ string? _(defaults to `true`)_
 	 */
 	cache?: boolean;
 };
@@ -181,9 +181,9 @@ function hasNodes(value: unknown): value is HTMLCollection | NodeList | Node[] {
 export function html(strings: TemplateStringsArray, ...values: unknown[]): Node[];
 
 /**
- * Create nodes from an HTML string or a template element
+ * Create nodes from an _HTML_ string or a template element
  *
- * @param value HTML string or id for a template element
+ * @param value _HTML_ string or ID for a template element
  * @param options Options for creating nodes
  * @returns Created nodes
  */
@@ -216,9 +216,9 @@ html.clear = (): void => {
 };
 
 /**
- * Remove cached template element for an HTML string or id
+ * Remove cached template element for an _HTML_ string or _ID_
  *
- * @param template HTML string or id for a template element
+ * @param template _HTML_ string or ID for a template element
  */
 html.remove = (template: string): void => {
 	templates.delete(template);
@@ -253,6 +253,7 @@ function replaceComments(origin: NodeList | Node[], replacements: Node[]): void
 
 /**
  * Sanitize one or more nodes, recursively
+ *
  * @param value Node or nodes to sanitize
  * @param options Sanitization options
  * @returns Sanitized nodes
@@ -283,7 +284,4 @@ const templates = new SizedMap<string, HTMLTemplateElement>(128);
 
 let parser: DOMParser;
 
-// @ts-expect-error debug
-window.templates = templates;
-
 // #endregion

package/src/index.ts

@@ -1,5 +1,6 @@
 import supportsTouch from './touch';
 
+export * from './aria';
 export {
 	booleanAttributes,
 	getAttribute,

package/src/internal/attribute.ts

@@ -142,9 +142,11 @@ export function updateAttribute(
 		element,
 		name,
 		isBoolean ? (next ? '' : null) : value,
-		// oxlint-disable-next-line typescript/unbound-method: using `.call` in `updateElementValue`
+		// Using `.call` in `updateElementValue`
+		// oxlint-disable-next-line typescript/unbound-method
 		element.setAttribute,
-		// oxlint-disable-next-line typescript/unbound-method: using `.call` in `updateElementValue`
+		// Using `.call` in `updateElementValue`
+		// oxlint-disable-next-line typescript/unbound-method
 		element.removeAttribute,
 		isBoolean,
 		false,

package/src/internal/element-value.ts

@@ -1,7 +1,6 @@
 import {isNullableOrWhitespace} from '@oscarpalmer/atoms/is';
 import {getString} from '@oscarpalmer/atoms/string';
 import {kebabCase} from '@oscarpalmer/atoms/string/case';
-import {isHTMLOrSVGElement} from '../is';
 import {isAttribute} from './attribute';
 
 // #region Functions
@@ -26,7 +25,7 @@ export function setElementValue(
 	callback: (element: Element, key: string, value: unknown, dispatch: boolean) => void,
 	style?: boolean,
 ): void {
-	if (!isHTMLOrSVGElement(element)) {
+	if (!(element instanceof Element)) {
 		return;
 	}
 
@@ -45,7 +44,7 @@ export function setElementValues(
 	callback: (element: Element, key: string, value: unknown, dispatch: boolean) => void,
 	style?: boolean,
 ): void {
-	if (!isHTMLOrSVGElement(element)) {
+	if (!(element instanceof Element)) {
 		return;
 	}
 

package/src/internal/is.ts

@@ -34,10 +34,10 @@ export function isEventTarget(value: unknown): value is EventTarget {
 }
 
 /**
- * Is the value an HTML or SVG element?
+ * Is the value an _HTML_ or _SVG_ element?
  *
  * @param value Value to check
- * @returns `true` if it's an HTML or SVG element, otherwise `false`
+ * @returns `true` if it's an _HTML_ or _SVG_ element, otherwise `false`
  */
 export function isHTMLOrSVGElement(value: unknown): value is HTMLElement | SVGElement {
 	return value instanceof HTMLElement || value instanceof SVGElement;

package/src/models.ts

@@ -1,3 +1,125 @@
+/**
+ * _ARIA_ attribute for an element
+ *
+ * _(https://www.w3.org/TR/wai-aria-1.3/#aria-attributes)_
+ */
+export type AriaAttribute = keyof AriaAttributes;
+
+/**
+ * _ARIA_ attribute for an element without the `aria-` prefix
+ *
+ * _(https://www.w3.org/TR/wai-aria-1.3/#aria-attributes)_
+ */
+export type AriaAttributeUnprefixed = keyof {
+	[Key in AriaAttribute as Key extends `aria-${infer Name}` ? Name : never]: string | null;
+};
+
+type AriaAttributes = {
+	[Key in keyof ARIAMixin as NormalizedName<Key>]: string | null;
+};
+
+type NormalizedName<Key extends string> = Key extends `aria${infer Name}`
+	? Name extends `${infer Part}Element`
+		? `aria-${Lowercase<Part>}`
+		: Name extends `${infer Part}Elements`
+			? `aria-${Lowercase<Part>}`
+			: `aria-${Lowercase<Name>}`
+	: never;
+
+/**
+ * _ARIA_ role for an element
+ *
+ * _(https://www.w3.org/TR/wai-aria-1.3/#role_definitions)_
+ */
+export type AriaRole =
+	| 'alert'
+	| 'alertdialog'
+	| 'application'
+	| 'article'
+	| 'banner'
+	| 'blockquote'
+	| 'button'
+	| 'caption'
+	| 'cell'
+	| 'checkbox'
+	| 'code'
+	| 'columnheader'
+	| 'combobox'
+	| 'comment'
+	| 'complementary'
+	| 'contentinfo'
+	| 'definition'
+	| 'deletion'
+	| 'dialog'
+	| 'directory'
+	| 'document'
+	| 'emphasis'
+	| 'feed'
+	| 'figure'
+	| 'form'
+	| 'generic'
+	| 'grid'
+	| 'gridcell'
+	| 'group'
+	| 'heading'
+	| 'img'
+	| 'insertion'
+	| 'link'
+	| 'list'
+	| 'listbox'
+	| 'listitem'
+	| 'log'
+	| 'main'
+	| 'mark'
+	| 'marquee'
+	| 'math'
+	| 'menu'
+	| 'menubar'
+	| 'menuitem'
+	| 'menuitemcheckbox'
+	| 'menuitemradio'
+	| 'meter'
+	| 'navigation'
+	| 'none'
+	| 'note'
+	| 'option'
+	| 'paragraph'
+	| 'presentation'
+	| 'progressbar'
+	| 'radio'
+	| 'radiogroup'
+	| 'region'
+	| 'row'
+	| 'rowgroup'
+	| 'rowheader'
+	| 'scrollbar'
+	| 'search'
+	| 'searchbox'
+	| 'sectionfooter'
+	| 'sectionheader'
+	| 'separator'
+	| 'slider'
+	| 'spinbutton'
+	| 'status'
+	| 'strong'
+	| 'subscript'
+	| 'suggestion'
+	| 'superscript'
+	| 'switch'
+	| 'tab'
+	| 'table'
+	| 'tablist'
+	| 'tabpanel'
+	| 'term'
+	| 'textbox'
+	| 'time'
+	| 'timer'
+	| 'toolbar'
+	| 'tooltip'
+	| 'tree'
+	| 'treegrid'
+	| 'treeitem';
+
 /**
  * Attribute for an element
  */

package/src/property/get.property.ts

@@ -1,6 +1,5 @@
 import type {Primitive} from '@oscarpalmer/atoms/models';
 import {camelCase} from '@oscarpalmer/atoms/string/case';
-import {isHTMLOrSVGElement} from '../internal/is';
 
 // #region Types
 
@@ -27,7 +26,7 @@ export function getProperties<Target extends Element, Property extends keyof Get
 ): Pick<GetProperties<Target>, Property> {
 	const values: Partial<GetProperties<Target>> = {};
 
-	if (!isHTMLOrSVGElement(target) || !Array.isArray(properties)) {
+	if (!(target instanceof Element && Array.isArray(properties))) {
 		return values as Pick<GetProperties<Target>, Property>;
 	}
 
@@ -55,12 +54,12 @@ export function getProperty<Target extends Element, Property extends keyof GetPr
 	target: Target,
 	property: Property,
 ): GetProperties<Target>[Property] {
-	if (isHTMLOrSVGElement(target) && typeof property === 'string') {
+	if (target instanceof Element && typeof property === 'string') {
 		return getPropertyValue(target, property) as GetProperties<Target>[Property];
 	}
 }
 
-function getPropertyValue(element: HTMLElement, property: string): unknown {
+function getPropertyValue(element: Element, property: string): unknown {
 	let actual = property;
 
 	if (!(actual in element)) {
@@ -68,7 +67,7 @@ function getPropertyValue(element: HTMLElement, property: string): unknown {
 	}
 
 	if (actual in element) {
-		return element[actual as keyof HTMLElement];
+		return element[actual as keyof Element];
 	}
 }
 

package/src/property/set.property.ts

@@ -4,7 +4,6 @@ import {setAttribute} from '../attribute';
 import type {DispatchedAttributeName} from '../attribute/set.attribute';
 import {booleanAttributesSet, dispatchedAttributes} from '../internal/attribute';
 import {updateProperty} from '../internal/property';
-import {isHTMLOrSVGElement} from '../is';
 
 // #region Types
 
@@ -37,7 +36,7 @@ export function setProperties<Target extends Element>(
 	properties: SetProperties<Target>,
 	dispatch?: boolean,
 ): void {
-	if (!isHTMLOrSVGElement(target) || !isPlainObject(properties)) {
+	if (!(target instanceof Element) || !isPlainObject(properties)) {
 		return;
 	}
 
@@ -85,7 +84,7 @@ export function setProperty<Target extends Element, Property extends keyof SetPr
 	value: SetProperties<Target>[Property],
 	dispatch?: boolean,
 ): void {
-	if (isHTMLOrSVGElement(target) && typeof property === 'string') {
+	if (target instanceof Element && typeof property === 'string') {
 		setPropertyValue(target, property, value, dispatch !== false);
 	}
 }