@oscarpalmer/toretto 0.48.0 → 0.49.0

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/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) === '') {