frontacles 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,9 +6,23 @@ 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.4.0...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)
 

package/README.md

@@ -7,14 +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 | [`isEmail`](#isemail) | 86 B |
-| url | [`Email`](#email) | 173 B |
-|  | **everything** | 328 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontacles",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Front-end utilities for artisans",
   "type": "module",
   "sideEffects": false,
@@ -12,21 +12,22 @@
   },
   "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",
-    "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:inspect": "eslint --inspect-config "
+    "lint:inspect": "eslint --inspect-config"
   },
   "files": [
     "CHANGELOG.md",
@@ -56,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/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;