@oscarpalmer/toretto 0.41.0 → 0.43.0

package/dist/index.d.mts

@@ -56,7 +56,8 @@ type TextDirection = 'ltr' | 'rtl';
  */
 declare const booleanAttributes: readonly string[];
 //#endregion
-//#region src/attribute/get.d.ts
+//#region src/attribute/get.attribute.d.ts
+type DataPrefixedName = `data-${string}`;
 /**
  * Get the value of a specific attribute from an element
  * @param element Element to get attribute from
@@ -64,7 +65,7 @@ declare const booleanAttributes: readonly string[];
  * @param parse Parse value? _(defaults to `true`)_
  * @returns Attribute value _(or `undefined`)_
  */
-declare function getAttribute(element: Element, name: `data-${string}`, parse?: boolean): unknown;
+declare function getAttribute(element: Element, name: DataPrefixedName, parse?: boolean): unknown;
 /**
  * Get the value of a specific attribute from an element
  * @param element Element to get attribute from
@@ -81,8 +82,8 @@ declare function getAttribute(element: Element, name: string): unknown;
  */
 declare function getAttributes<Key extends string>(element: Element, names: Key[], parseData?: boolean): Record<Key, unknown>;
 //#endregion
-//#region src/attribute/set.d.ts
-type DispatchedAttribute = 'checked' | 'open' | 'value';
+//#region src/attribute/set.attribute.d.ts
+type DispatchedAttributeName = 'checked' | 'open' | 'value';
 /**
  * Set an attribute on an element
  *
@@ -92,7 +93,7 @@ type DispatchedAttribute = 'checked' | 'open' | 'value';
  * @param value Attribute value
  * @param dispatch Dispatch event for attribute? _(defaults to `true`)_
  */
-declare function setAttribute<Name extends DispatchedAttribute>(element: Element, name: Name, value?: unknown, dispatch?: boolean): void;
+declare function setAttribute(element: Element, name: DispatchedAttributeName, value?: unknown, dispatch?: boolean): void;
 /**
  * Set an attribute on an element
  *
@@ -156,19 +157,6 @@ declare function isBooleanAttribute(attribute: Attr | Attribute): boolean;
  * @returns `true` if attribute is a boolean attribute
  */
 declare function isBooleanAttribute(name: string): boolean;
-/**
- * Is the attribute empty and not a boolean attribute?
- * @param attribute Attribute to check
- * @returns `true` if attribute is empty and not a boolean attribute
- */
-declare function isEmptyNonBooleanAttribute(attribute: Attr | Attribute): boolean;
-/**
- * Is the attribute empty and not a boolean attribute?
- * @param name Attribute name
- * @param value Attribute value
- * @returns `true` if attribute is empty and not a boolean attribute
- */
-declare function isEmptyNonBooleanAttribute(name: string, value: string): boolean;
 /**
  * Is the attribute an invalid boolean attribute?
  *
@@ -197,6 +185,32 @@ type PlainObject = Record<PropertyKey, unknown>;
  *
  * _(Thanks, type-fest!)_
  */
+type Primitive = null | undefined | string | number | boolean | symbol | bigint;
+/**
+ * Set required keys for a type
+ */
+//#endregion
+//#region src/create.d.ts
+type Properties<Target extends Element> = { [Property in keyof Target]?: Target[Property] extends Primitive ? Target[Property] : never };
+type Styles$1 = 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
+ * @returns Created element
+ */
+declare function createElement<TagName extends keyof HTMLElementTagNameMap>(tag: TagName, properties?: Properties<HTMLElementTagNameMap[TagName]>, attributes?: Record<string, unknown>, styles?: Styles$1): 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
+ * @returns Created element
+ */
+declare function createElement(tag: string, properties?: Properties<HTMLElement>, attributes?: Record<string, unknown>, styles?: Styles$1): HTMLUnknownElement;
 //#endregion
 //#region src/data.d.ts
 /**
@@ -398,38 +412,35 @@ declare function isFocusable(element: Element): boolean;
 declare function isTabbable(element: Element): boolean;
 //#endregion
 //#region src/html/index.d.ts
-type Html = {
-  /**
-   * Create nodes from an HTML string or a template element
-   * @param value HTML string or id for a template element
-   * @param options Options for creating nodes
-   * @returns Created nodes
-   */
-  (value: string, options?: HtmlOptions): Node[];
-  /**
-   * Create nodes from a template element
-   * @param template Template element
-   * @param options Options for creating nodes
-   * @returns Created nodes
-   */
-  (template: HTMLTemplateElement, options?: HtmlOptions): Node[];
-  /**
-   * Clear cache of template elements
-   */
-  clear(): void;
-  /**
-   * Remove cached template element for an HTML string or id
-   * @param template HTML string or id for a template element
-   */
-  remove(template: string): void;
-};
 type HtmlOptions = {
   /**
    * Cache template element for the HTML string? _(defaults to `true`)_
    */
   cache?: boolean;
 };
-declare const html: Html;
+/**
+ * Create nodes from a template string
+ * @returns Created nodes
+ */
+declare function html(strings: TemplateStringsArray, ...values: unknown[]): Node[];
+/**
+ * Create nodes from an HTML string or a template element
+ * @param value HTML string or id for a template element
+ * @param options Options for creating nodes
+ * @returns Created nodes
+ */
+declare function html(value: string, options?: HtmlOptions): Node[];
+/**
+ * Create nodes from a template element
+ * @param template Template element
+ * @param options Options for creating nodes
+ * @returns Created nodes
+ */
+declare function html(template: HTMLTemplateElement, options?: HtmlOptions): Node[];
+declare namespace html {
+  var clear: () => void;
+  var remove: (template: string) => void;
+}
 /**
  * Sanitize one or more nodes, recursively
  * @param value Node or nodes to sanitize
@@ -473,7 +484,53 @@ declare function isInDocument(node: Node): boolean;
  */
 declare function isInDocument(node: Node, document: Document): boolean;
 //#endregion
+//#region src/property/get.property.d.ts
+type GetProperties<Target extends Element> = { [Property in keyof Target as Target[Property] extends Primitive ? Property : never]?: Target[Property] };
+/**
+ * Get the values of one or more properties on an element
+ * @param target Target element
+ * @param properties Properties to get
+ * @returns Property values
+ */
+declare function getProperties<Target extends Element, Property extends keyof GetProperties<Target>>(target: Target, properties: Property[]): Pick<GetProperties<Target>, Property>;
+/**
+ * Get the value of a property on an element
+ * @param target Target element
+ * @param property Property to get
+ * @returns Property value
+ */
+declare function getProperty<Target extends Element, Property extends keyof GetProperties<Target>>(target: Target, property: Property): GetProperties<Target>[Property];
+//#endregion
+//#region src/property/set.property.d.ts
+type DispatchedPropertyValue<Target extends Element, Property extends DispatchedAttributeName> = Property extends keyof SetProperties<Target> ? SetProperties<Target>[Property] : never;
+type SetProperties<Target extends Element> = { [Property in keyof Target as Target[Property] extends Primitive ? Property : never]?: Target[Property] };
+/**
+ * Set the values of one or more properties on an element
+ *
+ * Also updates attributes for boolean/dispatchable properties, and if `dispatch` is `true`, will dispatch events for dispatchable properties
+ * @param target Target element
+ * @param properties Properties to set
+ * @param dispatch Dispatch events for properties? _(defaults to `true`)_
+ */
+declare function setProperties<Target extends Element>(target: Target, properties: SetProperties<Target>, dispatch?: boolean): void;
+/**
+ * Set the value for a dispatchable property on an element
+ * @param target Target element
+ * @param property Property to set
+ * @param value Value to set
+ * @param dispatch Dispatch event for property? _(defaults to `true`)_
+ */
+declare function setProperty<Target extends Element, Property extends DispatchedAttributeName>(target: Target, property: Property, value: DispatchedPropertyValue<Target, Property>, dispatch?: boolean): void;
+/**
+ * Set the value for a property on an element
+ * @param target Target element
+ * @param property Property to set
+ * @param value Value to set
+ */
+declare function setProperty<Target extends Element, Property extends keyof SetProperties<Target>>(target: Target, property: Property, value: SetProperties<Target>[Property]): void;
+//#endregion
 //#region src/style.d.ts
+type CSSStyleValues = Variables & CSSStyleDeclaration;
 type StyleToggler = {
   /**
    * Set the provided styles on the element
@@ -484,6 +541,8 @@ 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 };
 /**
  * Get a style from an element
  * @param element Element to get the style from
@@ -491,7 +550,7 @@ type StyleToggler = {
  * @param computed Get the computed style? _(defaults to `false`)_
  * @returns Style value
  */
-declare function getStyle(element: Element, property: keyof CSSStyleDeclaration, computed?: boolean): string | undefined;
+declare function getStyle(element: Element, property: keyof CSSStyleValues, computed?: boolean): string | undefined;
 /**
  * Get styles from an element
  * @param element Element to get the styles from
@@ -499,33 +558,37 @@ declare function getStyle(element: Element, property: keyof CSSStyleDeclaration,
  * @param computed Get the computed styles? _(defaults to `false`)_
  * @returns Style values
  */
-declare function getStyles<Property extends keyof CSSStyleDeclaration>(element: Element, properties: Property[], computed?: boolean): Record<Property, string | undefined>;
+declare function getStyles<Property extends keyof CSSStyleValues>(element: Element, properties: Property[], computed?: boolean): Record<Property, string | undefined>;
+/**
+ * Get the text direction of a node or element _(or document, if element is invalid)_
+ * @param node Node or element to get the text direction from
+ * @returns Text direction
+ */
+declare function getTextDirection(node: Element | Node): TextDirection;
 /**
- * Get the text direction of an element
- * @param element Element to get the text direction from
- * @param computed Get the computed text direction? _(defaults to `false`)_
+ * Get the text direction of the document
  * @returns Text direction
  */
-declare function getTextDirection(element: Element, computed?: boolean): TextDirection;
+declare function getTextDirection(): TextDirection;
 /**
  * Set a style on an element
  * @param element Element to set the style on
  * @param property Style name
  * @param value Style value
  */
-declare function setStyle(element: Element, property: keyof CSSStyleDeclaration, value?: string): void;
+declare function setStyle(element: Element, property: keyof CSSStyleValues, value?: unknown): void;
 /**
  * Set styles on an element
  * @param element Element to set the styles on
  * @param styles Styles to set
  */
-declare function setStyles(element: Element, styles: Partial<CSSStyleDeclaration>): void;
+declare function setStyles(element: Element, styles: Styles): void;
 /**
  * Toggle styles for an element
  * @param element Element to style
  * @param styles Styles to be set or removed
  * @returns Style toggler
  */
-declare function toggleStyles(element: Element, styles: Partial<CSSStyleDeclaration>): StyleToggler;
+declare function toggleStyles(element: Element, styles: Styles): StyleToggler;
 //#endregion
-export { findElement as $, findElement, findElements as $$, findElements, Attribute, CustomEventListener, EventPosition, RemovableEventListener, Selector, StyleToggler, TextDirection, booleanAttributes, dispatch, findAncestor, findRelatives, getAttribute, getAttributes, getData, getDistance, getElementUnderPointer, getFocusable, getPosition, getStyle, getStyles, getTabbable, getTextDirection, html, isBadAttribute, isBooleanAttribute, isChildNode, isEmptyNonBooleanAttribute, isEventTarget, isFocusable, isHTMLOrSVGElement, isInDocument, isInvalidBooleanAttribute, isTabbable, off, on, sanitize, setAttribute, setAttributes, setData, setStyle, setStyles, supportsTouch, toggleStyles };
+export { findElement as $, findElement, findElements as $$, findElements, Attribute, CustomEventListener, EventPosition, RemovableEventListener, Selector, StyleToggler, TextDirection, booleanAttributes, createElement, dispatch, findAncestor, findRelatives, getAttribute, getAttributes, getData, getDistance, getElementUnderPointer, getFocusable, getPosition, getProperties, getProperty, getStyle, getStyles, getTabbable, getTextDirection, html, isBadAttribute, isBooleanAttribute, isChildNode, isEventTarget, isFocusable, isHTMLOrSVGElement, isInDocument, isInvalidBooleanAttribute, isTabbable, off, on, sanitize, setAttribute, setAttributes, setData, setProperties, setProperty, setStyle, setStyles, supportsTouch, toggleStyles };