@oscarpalmer/toretto 0.48.0 → 0.49.1

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, attribute: AnyAriaAttribute): string | 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, 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
@@ -108,16 +149,9 @@ export function setAria(element: Element, attributes: AriaAttributeItem[]): void
  * @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, attributes: Record<string, unknown>): 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 +174,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,
@@ -151,7 +197,6 @@ function updateAriaAttribute(element: Element, key: string, value: unknown): voi
 		// oxlint-disable-next-line typescript/unbound-method
 		element.removeAttribute,
 		false,
-		false,
 	);
 }
 
@@ -163,4 +208,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)) {
@@ -38,13 +56,7 @@ export function getData(element: Element, keys: string | string[], parseValues?:
 	const noParse = parseValues === false;
 
 	if (typeof keys === 'string') {
-		const value = (element as HTMLElement).dataset[camelCase(keys)];
-
-		if (value === undefined) {
-			return;
-		}
-
-		return noParse ? value : parse(value);
+		return getDataValue(element, keys, noParse);
 	}
 
 	const {length} = keys;
@@ -53,18 +65,27 @@ export function getData(element: Element, keys: string | string[], parseValues?:
 
 	for (let index = 0; index < length; index += 1) {
 		const key = keys[index];
-		const value = (element as HTMLElement).dataset[camelCase(key)];
 
-		if (value == null) {
-			data[key] = undefined;
-		} else {
-			data[key] = noParse ? value : parse(value);
-		}
+		data[key] = getDataValue(element, key, noParse);
 	}
 
 	return data;
 }
 
+function getDataValue(element: Element, key: string, noParse: boolean): unknown {
+	const value = (element as HTMLElement).dataset[camelCase(key)];
+
+	if (value == null) {
+		return;
+	}
+
+	if (noParse) {
+		return value;
+	}
+
+	return parse(value) ?? value;
+}
+
 function getName(original: string): string {
 	return `${ATTRIBUTE_DATA_PREFIX}${kebabCase(original.replace(EXPRESSION_DATA_PREFIX, ''))}`;
 }
@@ -101,7 +122,6 @@ function updateDataAttribute(element: Element, key: string, value: unknown): voi
 		// Using `.call` in `updateElementValue`
 		// oxlint-disable-next-line typescript/unbound-method
 		element.removeAttribute,
-		false,
 		true,
 	);
 }

package/src/internal/attribute.ts

@@ -148,7 +148,6 @@ export function updateAttribute(
 		// Using `.call` in `updateElementValue`
 		// oxlint-disable-next-line typescript/unbound-method
 		element.removeAttribute,
-		isBoolean,
 		false,
 	);
 }

package/src/internal/element-value.ts

@@ -4,6 +4,14 @@ import {isAttribute} from './attribute';
 
 // #region Functions
 
+function getValueForAttribute(value: unknown, json: boolean): string | undefined {
+	if (typeof value === 'string') {
+		return value;
+	}
+
+	return json ? JSON.stringify(value) : getString(value);
+}
+
 function ignoreSetAttribute(element: Element, name: string): boolean {
 	if (element instanceof HTMLTextAreaElement && name === 'value') {
 		return true;
@@ -79,13 +87,12 @@ export function updateElementValue(
 	value: unknown,
 	set: (key: string, value: string) => void,
 	remove: (key: string) => void,
-	isBoolean: boolean,
 	json: boolean,
 ): void {
 	if (value == null) {
 		remove.call(element, key);
 	} else if (!ignoreSetAttribute(element, key)) {
-		set.call(element, key, json ? JSON.stringify(value) : getString(value));
+		set.call(element, key, getValueForAttribute(value, json) as string);
 	}
 }
 

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
  */