@oscarpalmer/toretto 0.47.3 → 0.49.0

package/src/aria.ts

@@ -1,13 +1,11 @@
 import {setElementValues, updateElementValue} from './internal/element-value';
-import type {AriaAttribute, AriaAttributeUnprefixed, AriaRole} from './models';
+import type {AnyAriaAttribute, AnyAriaBooleanAttribute, AriaRole} from './models';
 
 // #region Types
 
-type AnyAriaAttribute = AriaAttribute | AriaAttributeUnprefixed;
-
-type AriaAttributeItem = {
-	name: AnyAriaAttribute;
-	value?: string;
+type AriaAttributeItem<Name extends AnyAriaAttribute = AnyAriaAttribute> = {
+	name: Name;
+	value?: Name extends AnyAriaBooleanAttribute ? boolean | string : string;
 };
 
 // #endregion
@@ -18,10 +16,22 @@ type AriaAttributeItem = {
  * Get the value of a specific _ARIA_ attribute from an element
  *
  * @param element Element to get _ARIA_ attribute from
- * @param name _ARIA_ name
+ * @param name _ARIA_ attribute name
+ * @returns _ARIA_ value _(or `undefined`)_
+ */
+export function getAria(
+	element: Element,
+	name: AnyAriaBooleanAttribute,
+): boolean | string | undefined;
+
+/**
+ * Get the value of a specific _ARIA_ attribute from an element
+ *
+ * @param element Element to get _ARIA_ attribute from
+ * @param name _ARIA_ attribute name
  * @returns _ARIA_ value _(or `undefined`)_
  */
-export function getAria(element: Element, attribute: AnyAriaAttribute): string | undefined;
+export function getAria(element: Element, name: AnyAriaAttribute): string | undefined;
 
 /**
  * Get specific _ARIA_ attributes from an element
@@ -32,8 +42,12 @@ export function getAria(element: Element, attribute: AnyAriaAttribute): string |
  */
 export function getAria<Attribute extends AnyAriaAttribute>(
 	element: Element,
-	attributes: Attribute[],
-): Record<Attribute, string | undefined>;
+	names: Attribute[],
+): {
+	[Key in Attribute as Key extends `aria-${infer Name}`
+		? Name
+		: Key]: Key extends AnyAriaBooleanAttribute ? boolean | string | undefined : string | undefined;
+};
 
 export function getAria(element: Element, value: string | string[]): unknown {
 	if (!(element instanceof Element)) {
@@ -44,7 +58,7 @@ export function getAria(element: Element, value: string | string[]): unknown {
 		return typeof value === 'string' ? getAriaValue(element, value) : undefined;
 	}
 
-	const arias = {} as Record<string, string | undefined>;
+	const arias = {} as Record<string, unknown>;
 
 	const {length} = value;
 
@@ -59,8 +73,20 @@ export function getAria(element: Element, value: string | string[]): unknown {
 	return arias;
 }
 
-function getAriaValue(element: Element, attribute: string): string | undefined {
-	return element.getAttribute(getName(attribute)) ?? undefined;
+function getAriaValue(element: Element, attribute: string): unknown {
+	const name = getName(attribute);
+
+	const value = element.getAttribute(name) ?? undefined;
+
+	if (
+		ariaBooleanAttributesSet.has(name as never) &&
+		typeof value === 'string' &&
+		EXPRESSION_BOOLEAN.test(value)
+	) {
+		return value.toLowerCase() === 'true';
+	}
+
+	return value;
 }
 
 function getName(value: string): string {
@@ -88,7 +114,22 @@ export function getRole(element: Element): string | undefined {
  * @param attribute _ARIA_ attribute to set
  * @param value _ARIA_ attribute value
  */
-export function setAria(element: Element, attribute: AnyAriaAttribute, value?: unknown): void;
+export function setAria(
+	element: Element,
+	attribute: AnyAriaBooleanAttribute,
+	value?: boolean | string,
+): void;
+
+/**
+ * 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
@@ -110,14 +151,12 @@ export function setAria(element: Element, attributes: AriaAttributeItem[]): void
  */
 export function setAria(
 	element: Element,
-	attributes: Partial<Record<AnyAriaAttribute, unknown>>,
+	attributes: {
+		[Key in AnyAriaAttribute]?: Key extends AnyAriaBooleanAttribute ? boolean | string : string;
+	},
 ): void;
 
-export function setAria(
-	element: Element,
-	first: AnyAriaAttribute | AriaAttributeItem[] | Partial<Record<AnyAriaAttribute, unknown>>,
-	second?: unknown,
-): void {
+export function setAria(element: Element, first: unknown, second?: unknown): void {
 	setElementValues(element, first, second, null, updateAriaAttribute);
 }
 
@@ -140,10 +179,22 @@ export function setRole(element: Element, role?: AriaRole): void {
 }
 
 function updateAriaAttribute(element: Element, key: string, value: unknown): void {
+	const name = getName(key);
+
+	let actual = value;
+
+	if (
+		ariaBooleanAttributesSet.has(name as never) &&
+		typeof value === 'string' &&
+		EXPRESSION_BOOLEAN.test(value)
+	) {
+		actual = value.toLowerCase() === 'true';
+	}
+
 	updateElementValue(
 		element,
-		getName(key),
-		value,
+		name,
+		actual,
 		// Using `.call` in `updateElementValue`
 		// oxlint-disable-next-line typescript/unbound-method
 		element.setAttribute,
@@ -163,4 +214,33 @@ const ATTRIBUTE_ARIA_PREFIX = 'aria-';
 
 const EXPRESSION_ARIA_PREFIX = /^aria-/i;
 
+const EXPRESSION_BOOLEAN = /^(true|false)$/i;
+
+/**
+ * List of _ARIA_ attributes that can be treated as boolean values
+ */
+export const ariaBooleanAttributes: readonly AnyAriaBooleanAttribute[] = Object.freeze([
+	'aria-atomic',
+	'aria-busy',
+	'aria-checked',
+	'aria-current',
+	'aria-disabled',
+	'aria-expanded',
+	'aria-haspopup',
+	'aria-hidden',
+	'aria-invalid',
+	'aria-modal',
+	'aria-multiline',
+	'aria-multiselectable',
+	'aria-pressed',
+	'aria-readonly',
+	'aria-required',
+	'aria-selected',
+]);
+
+/**
+ * Set of _ARIA_ attributes that can be treated as boolean values
+ */
+export const ariaBooleanAttributesSet = new Set(ariaBooleanAttributes);
+
 // #endregion

package/src/create.ts

@@ -1,15 +1,29 @@
+import {isPlainObject} from '@oscarpalmer/atoms/is';
 import type {Primitive} from '@oscarpalmer/atoms/models';
+import {setAria} from './aria';
 import {setAttributes} from './attribute';
+import {setData} from './data';
+import type {AnyAriaAttribute, AnyAriaBooleanAttribute, CSSValues} from './models';
 import {setProperties} from './property';
 import {setStyles} from './style';
 
 // #region Types
 
-type Properties<Target extends Element> = {
-	[Property in keyof Target]?: Target[Property] extends Primitive ? Target[Property] : never;
+type CreateElementValues<Target extends Element> = {
+	aria?: CreateElementValuesAria;
+	attribute?: Record<string, unknown>;
+	data?: Record<string, unknown>;
+	property?: CreateElementValuesProperties<Target>;
+	style?: Partial<CSSValues>;
 };
 
-type Styles = Partial<Record<keyof CSSStyleDeclaration, unknown>>;
+type CreateElementValuesAria = {
+	[Key in AnyAriaAttribute]?: Key extends AnyAriaBooleanAttribute ? boolean | string : string;
+};
+
+type CreateElementValuesProperties<Target extends Element> = {
+	[Property in keyof Target]?: Target[Property] extends Primitive ? Target[Property] : never;
+};
 
 // #endregion
 
@@ -19,59 +33,60 @@ type Styles = Partial<Record<keyof CSSStyleDeclaration, unknown>>;
  * Creates an _HTML_ element with the specified tag name together with optional properties, attributes, and styles
  *
  * @param tag Tag name
- * @param properties Element properties
- * @param attributes Element attributes
- * @param styles Element styles
+ * @param values Element values
  * @returns Created element
  */
 export function createElement<TagName extends keyof HTMLElementTagNameMap>(
 	tag: TagName,
-	properties?: Properties<HTMLElementTagNameMap[TagName]>,
-	attributes?: Record<string, unknown>,
-	styles?: Styles,
+	values?: CreateElementValues<HTMLElementTagNameMap[TagName]>,
 ): HTMLElementTagNameMap[TagName];
 
 /**
  * Creates an _HTML_ element with the specified tag name together with optional properties, attributes, and styles
  *
  * @param tag Tag name
- * @param properties Element properties
- * @param attributes Element attributes
- * @param styles Element styles
+ * @param values Element values
  * @returns Created element
  */
 export function createElement(
 	tag: string,
-	properties?: Properties<HTMLElement>,
-	attributes?: Record<string, unknown>,
-	styles?: Styles,
+	values?: CreateElementValues<HTMLElement>,
 ): HTMLUnknownElement;
 
-export function createElement(
-	tag: string,
-	properties?: Properties<HTMLElement>,
-	attributes?: Record<string, unknown>,
-	styles?: Styles,
-): HTMLElement {
+export function createElement(tag: string, values?: CreateElementValues<HTMLElement>): HTMLElement {
 	if (typeof tag !== 'string') {
 		throw new TypeError(MESSAGE);
 	}
 
 	const element = document.createElement(tag);
 
-	if (properties != null) {
-		setProperties(element, properties);
-	}
+	const {aria, attribute, data, property, style} = getElementValues<HTMLElement>(values);
 
-	if (attributes != null) {
-		setAttributes(element, attributes);
-	}
+	setAria(element, aria ?? {});
+	setAttributes(element, attribute ?? {});
+	setData(element, data ?? {});
+	setProperties(element, property ?? {});
+	setStyles(element, style ?? {});
+
+	return element;
+}
 
-	if (styles != null) {
-		setStyles(element, styles);
+function getElementValues<Target extends Element>(input?: unknown): CreateElementValues<Target> {
+	if (!isPlainObject(input)) {
+		return {};
 	}
 
-	return element;
+	return {
+		aria: isPlainObject(input.aria) ? input.aria : undefined,
+		attribute: isPlainObject(input.attribute)
+			? (input.attribute as Record<string, unknown>)
+			: undefined,
+		data: isPlainObject(input.data) ? input.data : undefined,
+		property: isPlainObject(input.property)
+			? (input.property as CreateElementValuesProperties<Target>)
+			: undefined,
+		style: isPlainObject(input.style) ? input.style : undefined,
+	};
 }
 
 // #endregion

package/src/data.ts

@@ -7,28 +7,46 @@ import {EXPRESSION_DATA_PREFIX} from './internal/get-value';
 // #region Functions
 
 /**
- * Get a keyed data value from an element
+ * Get a keyed data value from an element, without parsing the value
  *
  * @param element Element to get data from
  * @param key Data key
- * @param parse Parse values? _(defaults to `true`)_
+ * @param parse Parse the value?
  * @returns Data value
  */
-export function getData(element: Element, key: string, parse?: boolean): unknown;
+export function getData(element: Element, key: string, parse: false): string | undefined;
 
 /**
- * Get keyed data values from an element
+ * Get a keyed data value from an element and parse the value
+ *
+ * @param element Element to get data from
+ * @param key Data key
+ * @returns Data value
+ */
+export function getData(element: Element, key: string): unknown;
+
+/**
+ * Get keyed data values from an element, without parsing the values
  *
  * @param element Element to get data from
  * @param keys Keys of the data values to get
- * @param parse Parse values? _(defaults to `true`)_
+ * @param parse Parse the values?
  * @returns Keyed data values
  */
 export function getData<Key extends string>(
 	element: Element,
 	keys: Key[],
-	parse?: boolean,
-): Record<Key, unknown>;
+	parse: false,
+): Record<Key, string | undefined>;
+
+/**
+ * Get keyed data values from an element and parse the values
+ *
+ * @param element Element to get data from
+ * @param keys Keys of the data values to get
+ * @returns Keyed data values
+ */
+export function getData<Key extends string>(element: Element, keys: Key[]): Record<Key, unknown>;
 
 export function getData(element: Element, keys: string | string[], parseValues?: boolean): unknown {
 	if (!(element instanceof Element)) {

package/src/event/index.ts

@@ -32,7 +32,7 @@ function createDispatchOptions(options: EventInit): EventInit {
 	};
 }
 
-function createEvent(type: string, options?: CustomEventInit): Event {
+function createEvent(type: string, options?: CustomEventInit): CustomEvent | Event {
 	const hasOptions = isPlainObject(options);
 
 	if (hasOptions && 'detail' in (options as CustomEventInit)) {
@@ -61,11 +61,11 @@ function createEventOptions(options?: AddEventListenerOptions): EventOptions {
  * @param type Type of event
  * @param options Options for event _(bubbles and is cancelable by default)_
  */
-export function dispatch<Type extends keyof HTMLElementEventMap>(
+export function dispatch<Type extends keyof HTMLElementEventMap, Options extends CustomEventInit>(
 	target: EventTarget,
 	type: Type,
-	options?: CustomEventInit,
-): void;
+	options?: Options,
+): Options extends {detail: infer Detail} ? CustomEvent<Detail> : Event;
 
 /**
  * Dispatch an event for a target
@@ -74,16 +74,26 @@ export function dispatch<Type extends keyof HTMLElementEventMap>(
  * @param type Type of event
  * @param options Options for event _(bubbles and is cancelable by default)_
  */
-export function dispatch(target: EventTarget, type: string, options?: CustomEventInit): void;
+export function dispatch<Options extends CustomEventInit>(
+	target: EventTarget,
+	type: string,
+	options?: Options,
+): Options extends {detail: infer Detail} ? CustomEvent<Detail> : Event;
 
 export function dispatch<Type extends keyof HTMLElementEventMap>(
 	target: EventTarget,
 	type: Type | string,
 	options?: CustomEventInit,
-): void {
-	if (isEventTarget(target) && typeof type === 'string') {
-		target.dispatchEvent(createEvent(type, options));
+): CustomEvent | Event | undefined {
+	if (!isEventTarget(target) || typeof type !== 'string') {
+		return;
 	}
+
+	const event = createEvent(type, options);
+
+	target.dispatchEvent(event);
+
+	return event;
 }
 
 /**

package/src/models.ts

@@ -1,3 +1,13 @@
+/**
+ * Any _ARIA_ attribute for an element _(both prefixed and unprefixed)_
+ */
+export type AnyAriaAttribute = AriaAttribute | AriaAttributeUnprefixed;
+
+/**
+ * Any _ARIA_ attribute for an element that can be set to a boolean value _(both prefixed and unprefixed)_
+ */
+export type AnyAriaBooleanAttribute = AriaBooleanAttribute | AriaBooleanAttributeUnprefixed;
+
 /**
  * _ARIA_ attribute for an element
  *
@@ -11,11 +21,39 @@ export type AriaAttribute = keyof AriaAttributes;
  * _(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;
+	[Key in AriaAttribute as Key extends `aria-${infer Name}` ? Name : never]: unknown;
 };
 
 type AriaAttributes = {
-	[Key in keyof ARIAMixin as NormalizedName<Key>]: string | null;
+	[Key in keyof ARIAMixin as NormalizedName<Key>]: unknown;
+};
+
+/**
+ * _ARIA_ attribute for an element that can be set to a boolean value
+ */
+export type AriaBooleanAttribute =
+	| 'aria-atomic'
+	| 'aria-busy'
+	| 'aria-checked'
+	| 'aria-current'
+	| 'aria-disabled'
+	| 'aria-expanded'
+	| 'aria-haspopup'
+	| 'aria-hidden'
+	| 'aria-invalid'
+	| 'aria-modal'
+	| 'aria-multiline'
+	| 'aria-multiselectable'
+	| 'aria-pressed'
+	| 'aria-readonly'
+	| 'aria-required'
+	| 'aria-selected';
+
+/**
+ * _ARIA_ attribute for an element that can be set to a boolean value, without the `aria-` prefix
+ */
+export type AriaBooleanAttributeUnprefixed = keyof {
+	[Key in AriaBooleanAttribute as Key extends `aria-${infer Name}` ? Name : never]: string | null;
 };
 
 type NormalizedName<Key extends string> = Key extends `aria${infer Name}`
@@ -128,6 +166,23 @@ export type Attribute = {
 	value: unknown;
 };
 
+/**
+ * CSS styles for an element
+ */
+export type CSSStyles = Record<keyof CSSStyleDeclaration, unknown>;
+
+/**
+ * CSSS values for an element _(both styles and variables)_
+ */
+export type CSSValues = CSSVariables & CSSStyles;
+
+/**
+ * CSS variables for an element
+ */
+export type CSSVariables<Value extends Record<string, unknown> = Record<string, unknown>> = {
+	[Property in keyof Value as `--${string & Property}`]?: unknown;
+};
+
 /**
  * Event listener for custom events
  */

package/src/style.ts

@@ -1,12 +1,10 @@
 import {getString} from '@oscarpalmer/atoms/string';
 import {setElementValues, updateElementValue} from './internal/element-value';
 import {getStyleValue} from './internal/get-value';
-import type {TextDirection} from './models';
+import type {CSSValues, TextDirection} from './models';
 
 // #region Types
 
-type CSSStyleValues = Variables & CSSStyleDeclaration;
-
 export type StyleToggler = {
 	/**
 	 * Set the provided styles on the element
@@ -18,14 +16,6 @@ export type StyleToggler = {
 	remove(): void;
 };
 
-type Styles = Partial<Record<keyof CSSStyleValues, unknown>>;
-
-type Variables<
-	Value extends Record<string, string | undefined> = Record<string, string | undefined>,
-> = {
-	[property in keyof Value as `--${string & property}`]?: string | undefined;
-};
-
 // #endregion
 
 // #region Functions
@@ -34,17 +24,17 @@ type Variables<
  * Get a style from an element
  *
  * @param element Element to get the style from
- * @param property Style name
+ * @param name Style name
  * @param computed Get the computed style? _(defaults to `false`)_
  * @returns Style value
  */
 export function getStyle(
 	element: Element,
-	property: keyof CSSStyleValues,
+	name: keyof CSSValues,
 	computed?: boolean,
 ): string | undefined {
-	if (element instanceof Element && typeof property === 'string') {
-		return getStyleValue(element, property, computed === true);
+	if (element instanceof Element && typeof name === 'string') {
+		return getStyleValue(element, name, computed === true);
 	}
 }
 
@@ -52,28 +42,28 @@ export function getStyle(
  * Get styles from an element
  *
  * @param element Element to get the styles from
- * @param properties Styles to get
+ * @param names Styles to get
  * @param computed Get the computed styles? _(defaults to `false`)_
  * @returns Style values
  */
-export function getStyles<Property extends keyof CSSStyleValues>(
+export function getStyles<Name extends keyof CSSValues>(
 	element: Element,
-	properties: Property[],
+	names: Name[],
 	computed?: boolean,
-): Record<Property, string | undefined> {
-	const styles = {} as Record<Property, string | undefined>;
+): Record<Name, string | undefined> {
+	const styles = {} as Record<Name, string | undefined>;
 
-	if (!(element instanceof Element && Array.isArray(properties))) {
+	if (!(element instanceof Element && Array.isArray(names))) {
 		return styles;
 	}
 
-	const {length} = properties;
+	const {length} = names;
 
 	for (let index = 0; index < length; index += 1) {
-		const property = properties[index];
+		const name = names[index];
 
-		if (typeof property === 'string') {
-			styles[property] = getStyleValue(element, property, computed === true) as never;
+		if (typeof name === 'string') {
+			styles[name] = getStyleValue(element, name, computed === true) as never;
 		}
 	}
 
@@ -120,11 +110,11 @@ export function getTextDirection(node?: Element | Node): TextDirection {
  * Set a style on an element
  *
  * @param element Element to set the style on
- * @param property Style name
+ * @param name Style name
  * @param value Style value
  */
-export function setStyle(element: Element, property: keyof CSSStyleValues, value?: unknown): void {
-	setElementValues(element, property as string, value, null, updateStyleProperty, true);
+export function setStyle(element: Element, name: keyof CSSValues, value?: unknown): void {
+	setElementValues(element, name as string, value, null, updateStyleProperty, true);
 }
 
 /**
@@ -133,7 +123,7 @@ export function setStyle(element: Element, property: keyof CSSStyleValues, value
  * @param element Element to set the styles on
  * @param styles Styles to set
  */
-export function setStyles(element: Element, styles: Styles): void {
+export function setStyles(element: Element, styles: Partial<CSSValues>): void {
 	setElementValues(element, styles as never, null, null, updateStyleProperty, true);
 }
 
@@ -144,11 +134,11 @@ export function setStyles(element: Element, styles: Styles): void {
  * @param styles Styles to be set or removed
  * @returns Style toggler
  */
-export function toggleStyles(element: Element, styles: Styles): StyleToggler {
+export function toggleStyles(element: Element, styles: Partial<CSSValues>): StyleToggler {
 	function toggle(set: boolean): void {
 		hasSet = set;
 
-		let next: Styles;
+		let next: Partial<CSSValues>;
 
 		if (set) {
 			values = getStyles(element, keys);
@@ -171,7 +161,7 @@ export function toggleStyles(element: Element, styles: Styles): StyleToggler {
 	const {length} = keys;
 
 	let hasSet = false;
-	let values: Record<string, string | undefined> = {};
+	let values: Record<string, unknown> = {};
 
 	return {
 		set(): void {
@@ -192,18 +182,18 @@ function updateStyleProperty(element: Element, key: string, value: unknown): voi
 		element,
 		key,
 		value,
-		function (this: Element, property: string, style: unknown) {
-			if (property.startsWith(VARIABLE_PREFIX)) {
-				(this as HTMLElement).style.setProperty(property, getString(style));
+		function (this: Element, name: string, style: unknown) {
+			if (name.startsWith(VARIABLE_PREFIX)) {
+				(this as HTMLElement).style.setProperty(name, getString(style));
 			} else {
-				(this as HTMLElement).style[property as never] = getString(style);
+				(this as HTMLElement).style[name as never] = getString(style);
 			}
 		},
-		function (this: Element, property: string) {
-			if (property.startsWith(VARIABLE_PREFIX)) {
-				(this as HTMLElement).style.removeProperty(property);
+		function (this: Element, name: string) {
+			if (name.startsWith(VARIABLE_PREFIX)) {
+				(this as HTMLElement).style.removeProperty(name);
 			} else {
-				(this as HTMLElement).style[property as never] = '';
+				(this as HTMLElement).style[name as never] = '';
 			}
 
 			if ((this as HTMLElement).getAttribute(ATTRIBUTE_STYLE) === '') {