frontacles 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -6,13 +6,45 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 Nothing for now.
 
+<!-- Compare with [last published version](https://github.com/frontacles/frontacles/compare/0.5.0...main).  -->
+
 <!-- ⚠️ Before a new release, make sure the documentation doesn't contain any **unreleased** mention.  -->
 
-Compare with [last published version](https://github.com/frontacles/frontacles/compare/0.2.3...main).
+## v0.5.0 (2026-01-24)
+
+Compare with [last published version](https://github.com/frontacles/frontacles/compare/0.4.0...0.5.0). 
+
+### New
+
+- Add [`setAttributes`](./README.md#setattributes), a function to update HTML attributes on any number of elements.
+
+### Under the hood
+
+- Setup tests for DOM utilities using Playwright via Vitest browser mode.
+- Migrate types testing from `tsd` to TSTyche.
+- Bump Node version from 20 to 22.
+
+## v0.4.0 (2025-03-08)
+
+Compare with [previous version](https://github.com/frontacles/frontacles/compare/0.3.0...0.4.0).
+
+### New
+
+- Add [`isEmail`](./README.md#isemail) to validate emails.
+
+### Documentation
+
+- It is now more explicit in types that `Email.canParse` expects a `string` or a `Stringable` (changed from `any|Email` to `any|string|Email|Stringable`).
+- Rephrase email documentation.
+
+### Under the hood
+
+- Centralize all benchmarks in [`./benchs`](./benchs).
+- Benchmark [`Email`](./benchs/url).
 
 ## v0.3.0 (2025-03-06)
 
-Compare with [last published version](https://github.com/frontacles/frontacles/compare/0.2.2...0.2.3).
+Compare with [previous version](https://github.com/frontacles/frontacles/compare/0.2.2...0.3.0).
 
 ### New
 
@@ -32,7 +64,7 @@ Compare with [last published version](https://github.com/frontacles/frontacles/c
 ### Under the hood
 
 - Shorten `round` by a couple of Bytes.
-- Benchmark [`round` implementations](./src/math/bench)
+- Benchmark [`round` implementations](./benchs/math)
 - Add [Valibot test suite](./src/url/test-utils/valibot-suite.js) to `Email` (all tests are passing!).
 
 ### Documentation
@@ -43,7 +75,7 @@ Compare with [last published version](https://github.com/frontacles/frontacles/c
 
 ## v0.2.2 (2025-03-01)
 
-Compare with [last published version](https://github.com/frontacles/frontacles/compare/0.2.1...0.2.2).
+Compare with [previous version](https://github.com/frontacles/frontacles/compare/0.2.1...0.2.2).
 
 ### Breaking
 

package/README.md

@@ -7,13 +7,131 @@ Cool utilities for front-end development (and potentially for Node).
 
 We love tiny bits (using brotli compression):
 
-| categories | util | size |
-| --- | --- | --- |
-| math | [`clamp`](#clamp) | 35 B |
-| math | [`round`](#round) | 38 B |
-| string | [`capitalize`](#capitalize) | 40 B |
-| url | [`Email`](#email) | 173 B |
-|  | **everything** | 252 B |
+| category | util | size | description |
+| --- | --- | --- | --- |
+| DOM | [`setAttributes`](#setattributes) | 338 B | Updates attributes of HTML or SVG element(s). |
+| math | [`clamp`](#clamp) | 35 B | Make sure a number stays in a given range. |
+| math | [`round`](#round) | 38 B | Round a number to a given precision. |
+| string | [`capitalize`](#capitalize) | 40 B | Capitalize the first letter of a string. |
+| URL | [`isEmail`](#isemail) | 86 B | Wheither a variable is a valid email address. |
+| URL | [`Email`](#email) | 173 B | An `Email` object with validation and separate access to an email username and domain. |
+|  | **everything** | 645 B | |
+
+## DOM utils
+
+### `setAttributes`
+
+Updates attributes of HTML element(s).
+
+```js
+import { setAttributes } from 'frontacles/dom'
+
+const widget = getElementById('animal-widget')
+
+// `<div name="Animal widget" loading="true">`
+setAttributes(widget, {
+  name: 'Animal widget'
+  loading: true,
+})
+```
+
+To remove an attribute, set its value to `false`, `null` or `undefined`.
+
+```js
+// `<div name="Animal widget">`
+setAttributes(widget, { loading: false })
+
+// `<div name="Animal widget" loading="false">`
+setAttributes(widget, { loading: 'false' })
+```
+
+`setAttributes` also accepts multiple elements (array or [HTML collection](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCollection)):
+
+```js
+const animals = widget.getElementsbyClassName('.list-item')
+
+// `<li class="list-item" data-cat="animals">cat</li>`
+setAttributes(animals, { 'data-cat': 'animals' })
+```
+
+When an attribute is an object, its properties are converted to `attrName-propName` attributes, making it helpful for any bulk update of `aria-*` or `data-*` attributes:
+
+```js
+setAttributes(el, {
+  loading: true,
+  aria: {
+    busy: true,
+    live: 'polite',
+  },
+  data: {
+    category: 'boats',
+    'max-items': 12,
+  },
+  user: {
+    id: 4,
+    name: 'Liz',
+  },
+})
+```
+
+The previous example gives:
+
+```html
+<div
+  loading="true"
+  aria-busy="true" aria-live="polite"
+  data-category="boats" data-max-items="12"
+  user-id="4" user-name="Liz"
+>
+```
+
+Like for non-object attributes, using `false`, `null` or `undefined` as property value will remove the matching attribute from the HTML:
+
+```js
+setAttributes(el, { data: { 'max-items': null }}) // no more `data-max-items`
+```
+
+> [!NOTE]  
+> `data` is using [`dataset`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset) under the hood, but differs from it: `setAttributes` removes any attribute with a `null` value while `dataset` turn `null` into a string. In the previous example, `el.dataset.maxItems = null` would have given `data-max-items="null"` instead of removing the attribute.
+
+`class` updates… CSS classes. It can be an array of CSS classes, a string containing one or more (space-separated) classes, or an object in the form of `{ className: state }`, defining which classes should be added or removed from the element.
+
+```js
+// <div class="btn btn--xl">
+setAttributes(el, { class: { btn: true, 'btn--xl': true }})
+
+// <div class="btn btn--xl card__btn">
+setAttributes(el, { class: ['card__btn'] })
+
+// <div class="btn btn--xl card__btn card__btn--special">
+setAttributes(el, { class: 'card__btn--special' })
+
+// <div class="btn btn--xl card__btn card__btn--special card__btn--1 card__btn--2">
+setAttributes(el, { class: 'card__btn--1 card__btn--2' })
+
+// <div class="btn card__btn card__btn--special card__btn--1 card__btn--2">
+setAttributes(el, { class: { 'btn--xl': false }})
+```
+
+When `style` is an object, it behaves like [`HTMLElement.style`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style). When it’s a string, it completely replaces the attribute.
+
+```js
+// <div style="color: red; opacity: 0.9">
+setAttributes(el, {
+  style: {
+    color: 'red',
+    opacity: .9
+  }
+})
+
+// <div style="color: red;">
+setAttributes(el, { style: { opacity: null }})
+
+// <div style="gap: 2px; opacity: .9;">
+setAttributes(el, { style: 'gap: 2px; opacity: .9;')
+```
+
+`setAttributes` also works on any SVG or descendant elements.
 
 ## Math utils
 
@@ -46,10 +164,9 @@ clamp(Infinity, 0, 10) // 10
 > [!NOTE]  
 > `clamp` mostly follows [`Math.clamp` TC39 proposal](https://github.com/tc39/proposal-math-clamp), except it doesn’t throw if you flip the order of the _min_ (2nd parameter) and _max_ (3rd parameter) numbers.
 
-
 ### `round`
 
-Round a number to the (optionally) provided precision.
+Round a number to the (optionally) provided decimal precision. The default precision is 0 (no decimal).
 
 ```js
 import { round } from 'frontacles/math'
@@ -66,7 +183,7 @@ round(687.3456, -1)  // 690
 round(687.3456, -2)  // 700
 ```
 
-Trying to round `Infinity` or to round a number to an _infinite_ precision is also possible:
+Using `Infinity` is also possible:
 
 ```js
 round(Infinity, -2) // Infinity
@@ -97,11 +214,40 @@ capitalize('صحراء') // 'صحراء' (Arabic)
 
 ## URL utils
 
+### `isEmail`
+
+Tells whether a string is a valid email.
+
+```js
+isEmail('someone@domain.tld') // true
+isEmail('invalid@email.com:3000') // false
+```
+
+> [!TIP]  
+> Should I use `isEmail` or [`Email.canParse`](#emailcanparse) to validate emails?
+>
+> Short answer: use `isEmail`.
+>
+> <details>
+> <summary>Nuanced answer</summary>
+>
+> Your use case:
+>
+> - If you **only need to validate** email addresses, use `isEmail`.
+> - If you also need to be able to get or set an email username or hostname **independently**, use `Email.canParse`.
+>
+> When using the `Email` class, you can still use `isEmail` if you want ultra-performance (e.g. your Node API validates tons of emails per seconds) because `isEmail` is 6✕ faster, at the cost of a bit less than 100 Bytes (compressed).
+>
+> The reason `isEmail` is faster is that it relies on a single RegExp while `Email.canParse` uses the browser built-in, which results in a bit more of computation, but with less code. For now, it’s not planned to use `isEmail` implementation in `Email.canParse` as it would increase its size by 50 Bytes.
+>
+> Keep in mind that **`Email.canParse` is fast enough** for the 99% use cases. Despite their implementation difference, both behave the same and pass the same tests.
+> </details>
+
 ### `Email`
 
-A class to instantiate an `Email` object or validate email addresses.
+A class to instantiate an `Email` object or validate email addresses. It extends the [`URL` object](https://developer.mozilla.org/en-US/docs/Web/API/URL) and has similar predictable behaviors.
 
-Unlike most libraries using [RegEx to validate a string is an email](https://github.com/colinhacks/zod/blob/e2b9a5f9ac67d13ada61cd8e4b1385eb850c7592/src/types.ts#L648-L663) (which is prone to [bugs](https://github.com/colinhacks/zod/issues/3913)), Frontacles `Email` relies on the same mechanism as your browser, making it robust, and very likely RFC compliant.
+#### `Email.constructor`
 
 ```js
 import { Email } from 'frontacles/url/email'
@@ -109,7 +255,23 @@ import { Email } from 'frontacles/url/email'
 const email = new Email('someone@domain.tld')
 ```
 
-Get or set the username and the hostname separately.
+Trying to instantiate an Email with an invalid address will throw. This behaviour is similar to the [`URL` constructor](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL), since `Email` relies on it under the hood.
+
+```js
+new Email('double@at@sign.com') // ❌ throw TypeError
+```
+
+Another behaviour from `URL`: passing an `Email` object to the `Email` constructor or to [`Email.canParse`](#emailcanparse) is possible.
+
+```js
+const email = new Email('someone@domain.tld')
+const alsoEmail = new Email(email) // ✅ a new Email object!
+Email.canParse(email) // ✅ true
+```
+
+#### `.username` and `.hostname`
+
+Get or set the email username and hostname separately.
 
 ```js
 email.username // 'someone'
@@ -121,35 +283,27 @@ email.hostname = 'newdomain.tld' // ✅ domain migrated
 const { username, hostname } = new Email('someone@domain.tld')
 ```
 
-An `Email` object is converted to a string when used along another string, or by directly calling `toString`.
+#### `.toString`
+
+In a string context, an `Email` object is automatically converted to a string, or manually by calling the `toString` method.
 
 ```js
 console.log(`email: ${email}`) // 'email: someone@newdomain.tld'
 console.log(email.toString()) // 'someone@newdomain.tld'
 ```
 
-Validate an email address with `Email.canParse`. It passes the complete Zod test suites, and beyond.
+#### `Email.canParse`
 
-```js
-Email.canParse('someone@domain.tld') // true
-Email.canParse('invalid@email.com:3000') // false
-```
+Validate an email address with `Email.canParse`.
 
-Trying to instantiate an Email with an invalid address will throw. This behaviour is similar to the [`URL` constructor](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL), since `Email` relies on it under the hood.
+Unlike most libraries using [RegExp to validate a string is an email](https://github.com/colinhacks/zod/blob/e2b9a5f9ac67d13ada61cd8e4b1385eb850c7592/src/types.ts#L648-L663) (which is prone to [bugs](https://github.com/colinhacks/zod/issues/3913)), Frontacles `Email` relies on the built-in `URL` mechanisms, making it robust, and very likely RFC compliant. It passes [popular libraries test suites](./src/url/test-utils), and beyond.
 
 ```js
-new Email('double@at@sign.com') // ❌ throw TypeError
+Email.canParse('someone@domain.tld') // true
+Email.canParse('invalid@email.com:3000') // false
 ```
 
-Another behaviour from the `URL` class: you can pass an `Email` object to the `Email` constructor (or to `Email.canParse`, but it doesn’t really make sense).
-
-```js
-const email = new Email('someone@domain.tld')
-
-const alsoEmail = new Email(email) // ✅ a new Email object!
-
-Email.canParse(email) // ✅ true
-```
+If `canParse` is all you need from the `Email` class, consider using [isEmail](#isemail) instead.
 
 ## Changelog
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontacles",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Front-end utilities for artisans",
   "type": "module",
   "sideEffects": false,
@@ -12,26 +12,26 @@
   },
   "types": "./types/index.d.ts",
   "engines": {
-    "node": ">=20.18.1"
+    "node": ">=22.12.0"
   },
   "scripts": {
     "types": "tsc && dts-bundle-generator --silent --no-banner=true -o types/index.d.ts types-transitive/index.d.ts",
     "posttypes": "node scripts/inject-jsdoc.mjs",
     "test": "vitest run",
-    "test:types": "npm exec tsd",
+    "test:types": "tstyche",
     "test:ui": "vitest --ui --coverage.enabled --coverage.exclude=types",
+    "test:watch": "vitest",
     "coverage": "vitest run --coverage --coverage.exclude=types",
-    "bench": "vitest bench",
-    "watch": "vitest watch",
+    "watch": "npm run test:watch",
     "build": "echo \"Nothing to build, this command is only here to please size-limit GitHub action\" && exit 0",
     "size": "size-limit",
     "lint": "eslint",
-    "lint-fix": "eslint --fix"
+    "lint:fix": "eslint --fix",
+    "lint:inspect": "eslint --inspect-config"
   },
   "files": [
     "CHANGELOG.md",
     "src/**/*.js",
-    "!src/**/bench",
     "!src/**/test-utils",
     "!src/**/*.test.js",
     "types/index.d.ts"
@@ -57,16 +57,18 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.9.0",
-    "@size-limit/preset-small-lib": "^11.1.4",
-    "@vitest/coverage-v8": "^3",
+    "@size-limit/preset-small-lib": "^12",
+    "@vitest/browser-playwright": "^4",
+    "@vitest/coverage-v8": "^4",
     "@vitest/eslint-plugin": "^1.0.1",
-    "@vitest/ui": "^3",
+    "@vitest/ui": "^4",
     "dts-bundle-generator": "^9.5.1",
     "eslint": "^9.9.0",
-    "size-limit": "^11.1.4",
-    "tsd": "^0.31.1",
+    "globals": "^17",
+    "size-limit": "^12",
+    "tstyche": "^6.0.2",
     "typescript": "^5.5.4",
-    "typescript-eslint": "^8.0.1",
-    "vitest": "^3"
+    "typescript-eslint": "^8",
+    "vitest": "^4"
   }
 }

package/src/dom/index.js

@@ -0,0 +1,121 @@
+/**
+ * Bulk update attributes of HTML element(s).
+ *
+ * Specific behaviour for the following types of values:
+ *
+ * - boolean, `null` and `undefined`:
+ *   - `true` adds the attribute to the HTML, with no value (`<p hidden="">`)
+ *   - `false`, `null` and `undefined` removes the attribute from the HTML
+ * - objects:
+ *   - `class` will add/remove CSS classes from `{ className: state }` entries
+ *   - `data` is pushed to `Element.dataset`, but a `data` property that is
+ *     `null` or `undefined` removes its `data-*` attribute from the HTML:
+ *     `{ data: { id: 1, enabled: false }}` gives `<p data-id="1">`
+ *   - `style` is pushed to `Element.style` (inline CSS):
+ *     `{ style: { color: 'red', gap: '2px' }}` gives
+ *     `<p style="color: red; gap: 2px;">`
+ *   - all other objects are converted the same way:
+ *     `aria: { label: 'Hello!' }` gives `<p aria-label="Hello!">`
+ * - `class` can also be a string with one or more classes (space-separated),
+ *   or an array of classes.
+ *
+ * @template {Element | Element[] | HTMLCollection} T
+ * @param {T} elements
+ * @param {Attributes} attributes
+ * @returns {T} The received element(s). Use it for method chaining.
+ */
+export const setAttributes = (elements, attributes) => {
+  const items = elements instanceof Element
+    ? [elements]
+    : [...elements]
+
+  attributes = normalizeAttributes(attributes)
+
+  items.forEach(element =>
+    attributes.forEach(([name, value]) => {
+      if (value == null) {
+        return element.removeAttribute(name)
+      }
+
+      // CSS `class`, as array or object.
+      if (name == 'class') {
+        return Array.isArray(value)
+          ? element.classList.add(...value)
+          : Object.entries(value).forEach(([className, classState]) =>
+            element.classList.toggle(className, classState)
+          )
+      }
+
+      // Only `data` and `style` can go in this `if`.
+      if (typeof value == 'object') {
+
+        // `style` attribute (inline styles)
+        if (name == 'style') {
+          return Object.assign(element.style, value)
+        }
+
+        // `data-*` attributes (using `dataset`)
+        Object.assign(element.dataset, value)
+
+        return Object.entries(value).forEach(([dataKey, dataValue]) => {
+          /**
+          * Remove `data-*` prop if their value is `null` or `undefined`,
+          * because `dataset` stringify them but `setAttributes` apply
+          * the logic of regular HTML attributes to all attributes.
+          */
+          if (dataValue == null) {
+            delete element.dataset[dataKey]
+          }
+        })
+      }
+
+      element.setAttribute(name, value)
+    })
+  )
+
+  return elements
+}
+
+/** @param {Record<string, any>} fnAttributes */
+const normalizeAttributes = fnAttributes => {
+  const attributes = { ...fnAttributes }
+
+  /**
+   * Normalize object attributes.
+   * It turns `{ key: { name: value }}` into `'key-name="value"'`.
+   */
+  Object.entries(attributes)
+    .filter(([name, value]) =>
+      value
+      && typeof value == 'object'
+      && !['class', 'data', 'style'].includes(name)
+    )
+    .forEach(([name, value]) => {
+      delete attributes[name]
+
+      Object.entries(value).forEach(([attrName, attrValue]) => {
+        attributes[`${name}-${attrName}`] = attrValue
+      })
+    })
+
+  // Normalize `class` attribute from string to array.
+  if (typeof attributes.class == 'string') {
+    attributes.class = attributes.class.split(' ')
+  }
+
+  // Normalize boolean attributes: `true` becomes `''`, `false` becomes `null`.
+  return Object.entries(attributes)
+    .map(([name, value]) => [
+      name,
+      typeof value == 'boolean'
+        ? (value ? '' : null)
+        : value // not boolean
+    ])
+}
+
+/** @typedef {boolean|string|number|null|undefined} AttributePrimitive */
+/** @typedef {AttributePrimitive | Record<string, AttributePrimitive>} AttributeValue */
+/** @typedef {Record<string, AttributeValue>} BaseAttributes */
+/** @typedef {{ class?: string | string[] | Record<string, boolean> }} ClassAttribute */
+/** @typedef {{ style?: AttributePrimitive | CSSStyleDeclaration }} StyleAttribute */
+/** @typedef {BaseAttributes | ClassAttribute | StyleAttribute} Attributes */

package/src/index.js

@@ -1,3 +1,4 @@
+export * from './dom/index.js'
 export * from './math/index.js'
 export * from './string/index.js'
 export * from './url/email.js'

package/src/url/email.js

@@ -17,6 +17,9 @@ export class Email extends URL {
   }
 
   /**
+   * The email address (`username@domain.tld`) as a string.
+   *
+   * (maintainer comment)
    * Replace the string representation of the top-level class (`URL`) to be an
    * email address instead of `ftp://username@domain.tld`. It is needed for
    * situation where type casting to string is involved (`console.log`…).
@@ -38,7 +41,7 @@ export class Email extends URL {
   /**
    * Whether or not an email address is parsable and valid.
    *
-   * @param {any|Email} address
+   * @param {any|string|Email|Stringable} address
    */
   static canParse(address) {
     try {
@@ -49,3 +52,17 @@ export class Email extends URL {
     }
   }
 }
+
+/**
+ * Whether or not an email address is parsable and valid.
+ *
+ * It uses WHATWG recommended RegExp: https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address
+ *
+ * @param {any|string|Stringable} address
+ */
+export const isEmail = address => /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/.test(address)
+
+/**
+ * @typedef {Object} Stringable
+ * @property {function(): string} toString - The object as a string.
+ */

package/types/index.d.ts

@@ -1,3 +1,14 @@
+export function setAttributes<T extends Element | Element[] | HTMLCollection>(elements: T, attributes: Attributes): T;
+export type AttributePrimitive = boolean | string | number | null | undefined;
+export type AttributeValue = AttributePrimitive | Record<string, AttributePrimitive>;
+export type BaseAttributes = Record<string, AttributeValue>;
+export type ClassAttribute = {
+	class?: string | string[] | Record<string, boolean>;
+};
+export type StyleAttribute = {
+	style?: AttributePrimitive | CSSStyleDeclaration;
+};
+export type Attributes = BaseAttributes | ClassAttribute | StyleAttribute;
 export function clamp(val: number, min: number, max: number): number;
 export function round(number: number, precision?: number): number;
 export function capitalize(str: string): string;
@@ -17,14 +28,21 @@ export class Email extends URL {
 	/**
 	 * Whether or not an email address is parsable and valid.
 	 *
-	 * @param {any|Email} address
+	 * @param {any|string|Email|Stringable} address
 	 */
-	static canParse(address: any | Email): boolean;
+	static canParse(address: any | string | Email | Stringable): boolean;
 	/**
 	 * @param {string|Email} address An email address like `someone@domain.tld`.
 	 */
 	constructor(address: string | Email);
 	#private;
 }
+export function isEmail(address: any | string | Stringable): boolean;
+export type Stringable = {
+	/**
+	 * - The object as a string.
+	 */
+	toString: () => string;
+};
 
 export {};