umaki 0.10.1 → 0.13.0

package/README.md

@@ -87,7 +87,9 @@ console.log(breakpoint); // e.g. 768 (default) or custom value if set
   - [videoPlayControl](#videoplaycontrol)
 - [Convert](#convert)
   - [changeDateStringToSpecificFormat](#changedatestringtospecificformat)
+  - [hexToRgb](#hextorgb)
   - [jsonStringToJsonObject](#jsonstringtojsonobject)
+  - [rgbToHex](#rgbtohex)
 - [EventControl](#eventcontrol)
   - [debounce](#debounce)
   - [throttle](#throttle)
@@ -104,6 +106,7 @@ console.log(breakpoint); // e.g. 768 (default) or custom value if set
   - [getRandomInt](#getrandomint)
   - [getRelativeTime](#getrelativetime)
   - [getRem](#getrem)
+  - [getRenderedLineHeight](#getrenderedlineheight)
   - [getScrollbarWidth](#getscrollbarwidth)
   - [getSessionStorage](#getsessionstorage)
   - [getStringLength](#getstringlength)
@@ -332,6 +335,21 @@ Note: This function focuses on timezone handling rather than locale-specific for
 
 [View file →](src/libs/convert/change-date-string-to-specific-format.ts)
 
+### hexToRgb
+
+A function that converts a hex color string to an RGB color object. Supports `#RGB` / `#RRGGBB` and the same forms without the leading `#`. Returns `undefined` for invalid input.
+
+```ts
+import { hexToRgb } from "umaki";
+
+hexToRgb("#ff0000"); // { r: 255, g: 0, b: 0 }
+hexToRgb("#fff"); // { r: 255, g: 255, b: 255 }
+hexToRgb("abc"); // { r: 170, g: 187, b: 204 }
+hexToRgb("#invalid"); // undefined
+```
+
+[View file →](src/libs/convert/hex-to-rgb.ts)
+
 ### jsonStringToJsonObject
 
 A function that converts a JSON string to a JSON object.
@@ -346,6 +364,22 @@ console.log(jsonObject); // { name: 'John', age: 30 }
 
 [View file →](src/libs/convert/json-string-to-json-object.ts)
 
+### rgbToHex
+
+A function that converts RGB color components to a 6-digit hex color string with leading `#`. Each component is rounded to the nearest integer and clamped to `[0, 255]`. Non-finite values (`NaN`, `Infinity`, `-Infinity`) are treated as `0`.
+
+```ts
+import { rgbToHex } from "umaki";
+
+rgbToHex(255, 0, 0); // '#ff0000'
+rgbToHex(170, 187, 204); // '#aabbcc'
+rgbToHex(1, 2, 3); // '#010203'
+rgbToHex(300, -10, 128.5); // '#ff0081' (clamped & rounded)
+rgbToHex(NaN, NaN, NaN); // '#000000'
+```
+
+[View file →](src/libs/convert/rgb-to-hex.ts)
+
 ## EventControl
 
 ### debounce
@@ -586,6 +620,48 @@ console.log(remValue); // '1rem'
 
 [View file →](src/libs/get/get-rem.ts)
 
+### getRenderedLineHeight
+
+Measures the line-height **as it is actually rendered** (in CSS pixels) for a target element by inserting a hidden probe element with the same font-related styles and dividing its multi-line height by the sample line count.
+
+This works around an iOS Safari quirk ([WebKit Bug #225695](https://bugs.webkit.org/show_bug.cgi?id=225695)) where fractional `line-height` values are floored to integer pixels at paint time. Stacking-line UIs that rely on `1lh` (e.g. `mask-image: repeating-linear-gradient` rules) drift on iOS Safari but match `getRenderedLineHeight` output. Returns `NaN` in SSR environments or when the probe cannot be measured.
+
+The caller is responsible for awaiting `document.fonts.ready` before measuring when font-loaded accuracy matters.
+
+```ts
+import { getRenderedLineHeight } from "umaki";
+
+const textEl = document.querySelector<HTMLElement>(".text");
+if (!textEl) return;
+
+await document.fonts.ready;
+
+const lh = getRenderedLineHeight(textEl);
+if (Number.isFinite(lh)) {
+  textEl.style.setProperty("--text-line-height", `${lh}px`);
+}
+```
+
+```css
+.text {
+  mask-image: repeating-linear-gradient(
+    to bottom,
+    transparent 0,
+    transparent calc(var(--text-line-height, 1lh) - 0.5px),
+    #000 calc(var(--text-line-height, 1lh) - 0.5px),
+    #000 var(--text-line-height, 1lh)
+  );
+}
+```
+
+You can adjust the sampling resolution via `sampleLines` (default `20`, minimum `2`):
+
+```ts
+const lh = getRenderedLineHeight(textEl, { sampleLines: 40 });
+```
+
+[View file →](src/libs/get/get-rendered-line-height.ts)
+
 ### getScrollbarWidth
 
 A function that retrieves the width of the scrollbar.
@@ -1288,7 +1364,7 @@ import { getUaData, sanitizeHtml } from "umaki";
 | `umaki/callback` | Callback utilities (tap, tapAsync) |
 | `umaki/config` | Configuration (setConfig, getConfig) |
 | `umaki/control` | Scroll control, video playback, etc. |
-| `umaki/convert` | Data conversion (dates, JSON) |
+| `umaki/convert` | Data conversion (dates, JSON, colors) |
 | `umaki/eventControl` | debounce, throttle |
 | `umaki/get` | Value retrieval (DOM, UA, etc.) |
 | `umaki/is` | Boolean checks (device detection, etc.) |

package/dist/index.cjs.js

@@ -11,7 +11,9 @@ const pd = require("./libs/control/pd.cjs.js");
 const scrollToHash = require("./libs/control/scroll-to-hash.cjs.js");
 const videoPlayControl = require("./libs/control/video-play-control.cjs.js");
 const changeDateStringToSpecificFormat = require("./libs/convert/change-date-string-to-specific-format.cjs.js");
+const hexToRgb = require("./libs/convert/hex-to-rgb.cjs.js");
 const jsonStringToJsonObject = require("./libs/convert/json-string-to-json-object.cjs.js");
+const rgbToHex = require("./libs/convert/rgb-to-hex.cjs.js");
 const debounce = require("./libs/eventControl/debounce.cjs.js");
 const throttle = require("./libs/eventControl/throttle.cjs.js");
 const getAspectRatio = require("./libs/get/get-aspect-ratio.cjs.js");
@@ -23,9 +25,10 @@ const getGravatarUrl = require("./libs/get/get-gravatar-url.cjs.js");
 const getOrientation = require("./libs/get/get-orientation.cjs.js");
 const getParentList = require("./libs/get/get-parent-list.cjs.js");
 const getQueryParams = require("./libs/get/get-query-params.cjs.js");
-const getRelativeTime = require("./libs/get/get-relative-time.cjs.js");
 const getRandomInt = require("./libs/get/get-random-int.cjs.js");
+const getRelativeTime = require("./libs/get/get-relative-time.cjs.js");
 const getRem = require("./libs/get/get-rem.cjs.js");
+const getRenderedLineHeight = require("./libs/get/get-rendered-line-height.cjs.js");
 const getScrollbarWidth = require("./libs/get/get-scrollbar-width.cjs.js");
 const getSessionStorage = require("./libs/get/get-session-storage.cjs.js");
 const getStringLength = require("./libs/get/get-string-length.cjs.js");
@@ -62,7 +65,6 @@ const waitForAllMediaLoaded = require("./libs/wait/wait-for-all-media-loaded.cjs
 exports.tap = tap.tap;
 exports.tapAsync = tapAsync.tapAsync;
 exports.defaultConfig = defaultConfig.defaultConfig;
-exports.currentConfig = getConfig.currentConfig;
 exports.getConfig = getConfig.getConfig;
 exports.getConfigValue = getConfig.getConfigValue;
 exports.setConfig = setConfig.setConfig;
@@ -72,7 +74,9 @@ exports.pd = pd.pd;
 exports.scrollToHash = scrollToHash.scrollToHash;
 exports.videoPlayControl = videoPlayControl.videoPlayControl;
 exports.changeDateStringToSpecificFormat = changeDateStringToSpecificFormat.changeDateStringToSpecificFormat;
+exports.hexToRgb = hexToRgb.hexToRgb;
 exports.jsonStringToJsonObject = jsonStringToJsonObject.jsonStringToJsonObject;
+exports.rgbToHex = rgbToHex.rgbToHex;
 exports.debounce = debounce.debounce;
 exports.throttle = throttle.throttle;
 exports.getAspectRatio = getAspectRatio.getAspectRatio;
@@ -84,9 +88,10 @@ exports.getGravatarUrl = getGravatarUrl.getGravatarUrl;
 exports.getOrientation = getOrientation.getOrientation;
 exports.getParentList = getParentList.getParentList;
 exports.getQueryParams = getQueryParams.getQueryParams;
-exports.getRelativeTime = getRelativeTime.getRelativeTime;
 exports.getRandomInt = getRandomInt.getRandomInt;
+exports.getRelativeTime = getRelativeTime.getRelativeTime;
 exports.getRem = getRem.getRem;
+exports.getRenderedLineHeight = getRenderedLineHeight.getRenderedLineHeight;
 exports.getScrollbarWidth = getScrollbarWidth.getScrollbarWidth;
 exports.getSessionStorage = getSessionStorage.getSessionStorage;
 exports.getStringLength = getStringLength.getStringLength;
@@ -109,6 +114,7 @@ exports.removeAttribute = removeAttribute.removeAttribute;
 exports.removeSessionStorage = removeSessionStorage.removeSessionStorage;
 exports.removeStylePropertyValue = removeStylePropertyValue.removeStylePropertyValue;
 exports.htmlSanitize = htmlSanitize.htmlSanitize;
+exports.sanitizeHtml = htmlSanitize.sanitizeHtml;
 exports.set100vh = set100vh.set100vh;
 exports.set100vw = set100vw.set100vw;
 exports.setAttribute = setAttribute.setAttribute;

package/dist/index.es.js

@@ -1,7 +1,7 @@
 import { tap } from "./libs/callback/tap.es.js";
 import { tapAsync } from "./libs/callback/tap-async.es.js";
 import { defaultConfig } from "./libs/config/default-config.es.js";
-import { currentConfig, getConfig, getConfigValue } from "./libs/config/get-config.es.js";
+import { getConfig, getConfigValue } from "./libs/config/get-config.es.js";
 import { setConfig } from "./libs/config/set-config.es.js";
 import { bgScrollStop } from "./libs/control/bg-scroll-stop.es.js";
 import { copyToClipboard } from "./libs/control/copy-to-clipboard.es.js";
@@ -9,7 +9,9 @@ import { pd } from "./libs/control/pd.es.js";
 import { scrollToHash } from "./libs/control/scroll-to-hash.es.js";
 import { videoPlayControl } from "./libs/control/video-play-control.es.js";
 import { changeDateStringToSpecificFormat } from "./libs/convert/change-date-string-to-specific-format.es.js";
+import { hexToRgb } from "./libs/convert/hex-to-rgb.es.js";
 import { jsonStringToJsonObject } from "./libs/convert/json-string-to-json-object.es.js";
+import { rgbToHex } from "./libs/convert/rgb-to-hex.es.js";
 import { debounce } from "./libs/eventControl/debounce.es.js";
 import { throttle } from "./libs/eventControl/throttle.es.js";
 import { getAspectRatio } from "./libs/get/get-aspect-ratio.es.js";
@@ -21,9 +23,10 @@ import { getGravatarUrl } from "./libs/get/get-gravatar-url.es.js";
 import { getOrientation } from "./libs/get/get-orientation.es.js";
 import { getParentList } from "./libs/get/get-parent-list.es.js";
 import { getQueryParams } from "./libs/get/get-query-params.es.js";
-import { getRelativeTime } from "./libs/get/get-relative-time.es.js";
 import { getRandomInt } from "./libs/get/get-random-int.es.js";
+import { getRelativeTime } from "./libs/get/get-relative-time.es.js";
 import { getRem } from "./libs/get/get-rem.es.js";
+import { getRenderedLineHeight } from "./libs/get/get-rendered-line-height.es.js";
 import { getScrollbarWidth } from "./libs/get/get-scrollbar-width.es.js";
 import { getSessionStorage } from "./libs/get/get-session-storage.es.js";
 import { getStringLength } from "./libs/get/get-string-length.es.js";
@@ -45,7 +48,7 @@ import { removeAllHtmlTags } from "./libs/remove/remove-all-html-tags.es.js";
 import { removeAttribute } from "./libs/remove/remove-attribute.es.js";
 import { removeSessionStorage } from "./libs/remove/remove-session-storage.es.js";
 import { removeStylePropertyValue } from "./libs/remove/remove-style-property-value.es.js";
-import { htmlSanitize } from "./libs/security/html-sanitize.es.js";
+import { htmlSanitize, sanitizeHtml } from "./libs/security/html-sanitize.es.js";
 import { set100vh } from "./libs/set/set-100vh.es.js";
 import { set100vw } from "./libs/set/set-100vw.es.js";
 import { setAttribute } from "./libs/set/set-attribute.es.js";
@@ -62,7 +65,6 @@ export {
   changeDateStringToSpecificFormat,
   checkDeviceSize,
   copyToClipboard,
-  currentConfig,
   debounce,
   defaultConfig,
   getAspectRatio,
@@ -79,12 +81,14 @@ export {
   getRandomInt,
   getRelativeTime,
   getRem,
+  getRenderedLineHeight,
   getScrollbarWidth,
   getSessionStorage,
   getStringLength,
   getStylePropertyValue,
   getStylePropertyValueToNumber,
   getUaData,
+  hexToRgb,
   htmlSanitize,
   isAfterDateTime,
   isBetweenDateTime,
@@ -102,6 +106,8 @@ export {
   removeAttribute,
   removeSessionStorage,
   removeStylePropertyValue,
+  rgbToHex,
+  sanitizeHtml,
   scrollToHash,
   set100vh,
   set100vw,

package/dist/libs/config/_internal.cjs.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const defaultConfig = require("./default-config.cjs.js");
+const currentConfig = { ...defaultConfig.defaultConfig };
+exports.currentConfig = currentConfig;

package/dist/libs/config/_internal.d.ts

@@ -0,0 +1,6 @@
+import { UmakiConfig } from './types';
+/**
+ * Internal module for shared configuration state.
+ * This module should NOT be exported publicly.
+ */
+export declare const currentConfig: UmakiConfig;

package/dist/libs/config/_internal.es.js

@@ -0,0 +1,5 @@
+import { defaultConfig } from "./default-config.es.js";
+const currentConfig = { ...defaultConfig };
+export {
+  currentConfig
+};

package/dist/libs/config/get-config.cjs.js

@@ -1,13 +1,11 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const defaultConfig = require("./default-config.cjs.js");
-const currentConfig = { ...defaultConfig.defaultConfig };
+const _internal = require("./_internal.cjs.js");
 const getConfig = () => {
-  return { ...currentConfig };
+  return { ..._internal.currentConfig };
 };
 const getConfigValue = (key) => {
-  return currentConfig[key];
+  return _internal.currentConfig[key];
 };
-exports.currentConfig = currentConfig;
 exports.getConfig = getConfig;
 exports.getConfigValue = getConfigValue;

package/dist/libs/config/get-config.d.ts

@@ -1,5 +1,4 @@
 import { UmakiConfig } from './types';
-declare const currentConfig: UmakiConfig;
 /**
  * Get the current configuration
  * @returns The current configuration object
@@ -11,4 +10,3 @@ export declare const getConfig: () => UmakiConfig;
  * @returns The value for the specified key, or undefined if the key doesn't exist
  */
 export declare const getConfigValue: <K extends keyof UmakiConfig>(key: K) => UmakiConfig[K];
-export { currentConfig };

package/dist/libs/config/get-config.es.js

@@ -1,5 +1,4 @@
-import { defaultConfig } from "./default-config.es.js";
-const currentConfig = { ...defaultConfig };
+import { currentConfig } from "./_internal.es.js";
 const getConfig = () => {
   return { ...currentConfig };
 };
@@ -7,7 +6,6 @@ const getConfigValue = (key) => {
   return currentConfig[key];
 };
 export {
-  currentConfig,
   getConfig,
   getConfigValue
 };

package/dist/libs/config/index.cjs.js

@@ -4,7 +4,6 @@ const defaultConfig = require("./default-config.cjs.js");
 const getConfig = require("./get-config.cjs.js");
 const setConfig = require("./set-config.cjs.js");
 exports.defaultConfig = defaultConfig.defaultConfig;
-exports.currentConfig = getConfig.currentConfig;
 exports.getConfig = getConfig.getConfig;
 exports.getConfigValue = getConfig.getConfigValue;
 exports.setConfig = setConfig.setConfig;

package/dist/libs/config/index.es.js

@@ -1,8 +1,7 @@
 import { defaultConfig } from "./default-config.es.js";
-import { currentConfig, getConfig, getConfigValue } from "./get-config.es.js";
+import { getConfig, getConfigValue } from "./get-config.es.js";
 import { setConfig } from "./set-config.es.js";
 export {
-  currentConfig,
   defaultConfig,
   getConfig,
   getConfigValue,

package/dist/libs/config/set-config.cjs.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const getConfig = require("./get-config.cjs.js");
+const _internal = require("./_internal.cjs.js");
 const setConfig = (config) => {
-  Object.assign(getConfig.currentConfig, config);
-  return { ...getConfig.currentConfig };
+  Object.assign(_internal.currentConfig, config);
+  return { ..._internal.currentConfig };
 };
 exports.setConfig = setConfig;

package/dist/libs/config/set-config.es.js

@@ -1,4 +1,4 @@
-import { currentConfig } from "./get-config.es.js";
+import { currentConfig } from "./_internal.es.js";
 const setConfig = (config) => {
   Object.assign(currentConfig, config);
   return { ...currentConfig };

package/dist/libs/convert/hex-to-rgb.cjs.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const HEX_PATTERN = /^[0-9a-fA-F]+$/;
+const hexToRgb = (hex) => {
+  const trimmed = hex.trim();
+  const normalized = trimmed.startsWith("#") ? trimmed.slice(1) : trimmed;
+  if (!HEX_PATTERN.test(normalized)) return void 0;
+  let expanded;
+  if (normalized.length === 3) {
+    expanded = `${normalized[0]}${normalized[0]}${normalized[1]}${normalized[1]}${normalized[2]}${normalized[2]}`;
+  } else if (normalized.length === 6) {
+    expanded = normalized;
+  } else {
+    return void 0;
+  }
+  return {
+    r: Number.parseInt(expanded.slice(0, 2), 16),
+    g: Number.parseInt(expanded.slice(2, 4), 16),
+    b: Number.parseInt(expanded.slice(4, 6), 16)
+  };
+};
+exports.hexToRgb = hexToRgb;

package/dist/libs/convert/hex-to-rgb.d.ts

@@ -0,0 +1,16 @@
+/**
+ * RGB color components in 0-255 range.
+ */
+export interface RgbColor {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * Converts a hex color string to an RGB color object.
+ * Supports `#RGB`, `#RRGGBB` and the same forms without the leading `#`.
+ *
+ * @param hex - Hex color string (e.g. `#fff`, `#ff0000`, `ff0000`)
+ * @returns RGB color object, or `undefined` if the input is not a valid hex color string.
+ */
+export declare const hexToRgb: (hex: string) => RgbColor | undefined;

package/dist/libs/convert/hex-to-rgb.es.js

@@ -0,0 +1,22 @@
+const HEX_PATTERN = /^[0-9a-fA-F]+$/;
+const hexToRgb = (hex) => {
+  const trimmed = hex.trim();
+  const normalized = trimmed.startsWith("#") ? trimmed.slice(1) : trimmed;
+  if (!HEX_PATTERN.test(normalized)) return void 0;
+  let expanded;
+  if (normalized.length === 3) {
+    expanded = `${normalized[0]}${normalized[0]}${normalized[1]}${normalized[1]}${normalized[2]}${normalized[2]}`;
+  } else if (normalized.length === 6) {
+    expanded = normalized;
+  } else {
+    return void 0;
+  }
+  return {
+    r: Number.parseInt(expanded.slice(0, 2), 16),
+    g: Number.parseInt(expanded.slice(2, 4), 16),
+    b: Number.parseInt(expanded.slice(4, 6), 16)
+  };
+};
+export {
+  hexToRgb
+};

package/dist/libs/convert/hex-to-rgb.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/libs/convert/index.cjs.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const changeDateStringToSpecificFormat = require("./change-date-string-to-specific-format.cjs.js");
+const hexToRgb = require("./hex-to-rgb.cjs.js");
 const jsonStringToJsonObject = require("./json-string-to-json-object.cjs.js");
+const rgbToHex = require("./rgb-to-hex.cjs.js");
 exports.changeDateStringToSpecificFormat = changeDateStringToSpecificFormat.changeDateStringToSpecificFormat;
+exports.hexToRgb = hexToRgb.hexToRgb;
 exports.jsonStringToJsonObject = jsonStringToJsonObject.jsonStringToJsonObject;
+exports.rgbToHex = rgbToHex.rgbToHex;

package/dist/libs/convert/index.d.ts

@@ -2,4 +2,6 @@
  * Convert functions
  */
 export * from './change-date-string-to-specific-format';
+export * from './hex-to-rgb';
 export * from './json-string-to-json-object';
+export * from './rgb-to-hex';

package/dist/libs/convert/index.es.js

@@ -1,6 +1,10 @@
 import { changeDateStringToSpecificFormat } from "./change-date-string-to-specific-format.es.js";
+import { hexToRgb } from "./hex-to-rgb.es.js";
 import { jsonStringToJsonObject } from "./json-string-to-json-object.es.js";
+import { rgbToHex } from "./rgb-to-hex.es.js";
 export {
   changeDateStringToSpecificFormat,
-  jsonStringToJsonObject
+  hexToRgb,
+  jsonStringToJsonObject,
+  rgbToHex
 };

package/dist/libs/convert/rgb-to-hex.cjs.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const sanitizeComponent = (value) => {
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(255, Math.round(value)));
+};
+const toHexPair = (value) => sanitizeComponent(value).toString(16).padStart(2, "0");
+const rgbToHex = (r, g, b) => `#${toHexPair(r)}${toHexPair(g)}${toHexPair(b)}`;
+exports.rgbToHex = rgbToHex;

package/dist/libs/convert/rgb-to-hex.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Converts RGB color components to a 6-digit hex color string with leading `#`.
+ *
+ * Each component is rounded to the nearest integer and clamped to `[0, 255]`.
+ * Non-finite values (`NaN`, `Infinity`, `-Infinity`) are treated as `0`.
+ *
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @returns Lowercase hex color string (e.g. `#ff0000`)
+ */
+export declare const rgbToHex: (r: number, g: number, b: number) => string;

package/dist/libs/convert/rgb-to-hex.es.js

@@ -0,0 +1,9 @@
+const sanitizeComponent = (value) => {
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(255, Math.round(value)));
+};
+const toHexPair = (value) => sanitizeComponent(value).toString(16).padStart(2, "0");
+const rgbToHex = (r, g, b) => `#${toHexPair(r)}${toHexPair(g)}${toHexPair(b)}`;
+export {
+  rgbToHex
+};

package/dist/libs/convert/rgb-to-hex.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/libs/eventControl/debounce.cjs.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const debounce = (fn, delay) => {
+  if (delay < 0 || !Number.isFinite(delay)) {
+    throw new Error("delay must be a non-negative finite number");
+  }
   let timeoutId = null;
   return (...args) => {
     timeoutId && clearTimeout(timeoutId);

package/dist/libs/eventControl/debounce.d.ts

@@ -4,8 +4,9 @@ type DebounceProcedure = (...args: unknown[]) => void;
  *
  * @template F - The type of the function to debounce.
  * @param {F} fn - The function to debounce.
- * @param {number} delay - The number of milliseconds to delay.
+ * @param {number} delay - The number of milliseconds to delay. Must be a non-negative finite number.
  * @returns {(...args: Parameters<F>) => void} - A debounced version of the provided function.
+ * @throws {Error} If delay is negative or not finite.
  */
 export declare const debounce: <F extends DebounceProcedure>(fn: F, delay: number) => ((...args: Parameters<F>) => void);
 export {};

package/dist/libs/eventControl/debounce.es.js

@@ -1,4 +1,7 @@
 const debounce = (fn, delay) => {
+  if (delay < 0 || !Number.isFinite(delay)) {
+    throw new Error("delay must be a non-negative finite number");
+  }
   let timeoutId = null;
   return (...args) => {
     timeoutId && clearTimeout(timeoutId);

package/dist/libs/eventControl/throttle.cjs.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const throttle = (fn, wait) => {
+  if (wait < 0 || !Number.isFinite(wait)) {
+    throw new Error("wait must be a non-negative finite number");
+  }
   let lastCallTime = 0;
   return (...args) => {
     const currentTime = Date.now();

package/dist/libs/eventControl/throttle.d.ts

@@ -5,8 +5,9 @@ type ThrottleFunction = (...args: unknown[]) => void;
  *
  * @template F - The type of the function to be throttled.
  * @param fn - The function to throttle.
- * @param wait - The number of milliseconds to wait before allowing the next execution.
+ * @param wait - The number of milliseconds to wait before allowing the next execution. Must be a non-negative finite number.
  * @returns A throttled version of the provided function.
+ * @throws {Error} If wait is negative or not finite.
  */
 export declare const throttle: <F extends ThrottleFunction>(fn: F, wait: number) => ((...args: Parameters<F>) => void);
 export {};

package/dist/libs/eventControl/throttle.es.js

@@ -1,4 +1,7 @@
 const throttle = (fn, wait) => {
+  if (wait < 0 || !Number.isFinite(wait)) {
+    throw new Error("wait must be a non-negative finite number");
+  }
   let lastCallTime = 0;
   return (...args) => {
     const currentTime = Date.now();

package/dist/libs/get/get-aspect-ratio.cjs.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const getGcd = require("./get-gcd.cjs.js");
 const getAspectRatio = (w, h) => {
+  if (w <= 0 || h <= 0 || !Number.isFinite(w) || !Number.isFinite(h)) {
+    throw new Error("Width and height must be positive finite numbers");
+  }
   const gcd = getGcd.getGcd(w, h);
   return { w: w / gcd, h: h / gcd };
 };

package/dist/libs/get/get-aspect-ratio.d.ts

@@ -1,9 +1,10 @@
 /**
  * Returns the aspect ratio of the given width and height.
  *
- * @param w - The width value.
- * @param h - The height value.
+ * @param w - The width value. Must be a positive number.
+ * @param h - The height value. Must be a positive number.
  * @returns An object containing the width and height of the aspect ratio.
+ * @throws {Error} If width or height is not a positive number.
  */
 export declare const getAspectRatio: (w: number, h: number) => {
     w: number;

package/dist/libs/get/get-aspect-ratio.es.js

@@ -1,5 +1,8 @@
 import { getGcd } from "./get-gcd.es.js";
 const getAspectRatio = (w, h) => {
+  if (w <= 0 || h <= 0 || !Number.isFinite(w) || !Number.isFinite(h)) {
+    throw new Error("Width and height must be positive finite numbers");
+  }
   const gcd = getGcd(w, h);
   return { w: w / gcd, h: h / gcd };
 };

package/dist/libs/get/get-orientation.cjs.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const getOrientation = () => {
+  if (typeof window === "undefined") {
+    return "portrait";
+  }
   const isLandscape = window.matchMedia("(orientation: landscape)").matches;
   return isLandscape ? "landscape" : "portrait";
 };

package/dist/libs/get/get-orientation.d.ts

@@ -2,5 +2,6 @@
  * Retrieves the current orientation of the device.
  *
  * @returns {'landscape' | 'portrait'} The current orientation, either 'landscape' or 'portrait'.
+ * Returns 'portrait' as default in SSR environments where window is undefined.
  */
 export declare const getOrientation: () => "landscape" | "portrait";

package/dist/libs/get/get-orientation.es.js

@@ -1,4 +1,7 @@
 const getOrientation = () => {
+  if (typeof window === "undefined") {
+    return "portrait";
+  }
   const isLandscape = window.matchMedia("(orientation: landscape)").matches;
   return isLandscape ? "landscape" : "portrait";
 };

package/dist/libs/get/get-rendered-line-height.cjs.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const DEFAULT_SAMPLE_LINES = 20;
+const MIN_SAMPLE_LINES = 2;
+const MAX_SAMPLE_LINES = 100;
+const normalizeSampleLines = (value) => {
+  const raw = value ?? DEFAULT_SAMPLE_LINES;
+  if (!Number.isFinite(raw)) return DEFAULT_SAMPLE_LINES;
+  return Math.min(MAX_SAMPLE_LINES, Math.max(MIN_SAMPLE_LINES, Math.floor(raw)));
+};
+const getRenderedLineHeight = (element, options) => {
+  if (typeof window === "undefined") return Number.NaN;
+  const sampleLines = normalizeSampleLines(options?.sampleLines);
+  const ownerDocument = element.ownerDocument;
+  const host = ownerDocument?.body;
+  const view = ownerDocument?.defaultView;
+  if (!host || !view) return Number.NaN;
+  const cs = view.getComputedStyle(element);
+  const probe = ownerDocument.createElement("div");
+  const style = probe.style;
+  style.position = "absolute";
+  style.left = "-9999px";
+  style.top = "0";
+  style.visibility = "hidden";
+  style.pointerEvents = "none";
+  style.margin = "0";
+  style.padding = "0";
+  style.border = "0";
+  style.whiteSpace = "pre";
+  style.fontFamily = cs.fontFamily;
+  style.fontSize = cs.fontSize;
+  style.fontWeight = cs.fontWeight;
+  style.fontStyle = cs.fontStyle;
+  style.lineHeight = cs.lineHeight;
+  style.letterSpacing = cs.letterSpacing;
+  style.fontFeatureSettings = cs.fontFeatureSettings;
+  if (cs.fontVariationSettings) {
+    style.fontVariationSettings = cs.fontVariationSettings;
+  }
+  for (let i = 0; i < sampleLines; i++) {
+    if (i > 0) probe.appendChild(ownerDocument.createElement("br"));
+    probe.appendChild(ownerDocument.createTextNode("X"));
+  }
+  host.appendChild(probe);
+  try {
+    const probeHeight = probe.getBoundingClientRect().height;
+    if (probeHeight <= 0) return Number.NaN;
+    return probeHeight / sampleLines;
+  } catch {
+    return Number.NaN;
+  } finally {
+    if (probe.parentNode === host) {
+      host.removeChild(probe);
+    }
+  }
+};
+exports.getRenderedLineHeight = getRenderedLineHeight;

package/dist/libs/get/get-rendered-line-height.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Options for {@link getRenderedLineHeight}.
+ */
+export type GetRenderedLineHeightOptions = {
+    /**
+     * Number of lines used to measure the rendered line-height. Higher values
+     * yield a more precise per-line average. Clamped to the range [2, 100];
+     * non-finite values fall back to the default.
+     *
+     * @default 20
+     */
+    sampleLines?: number;
+};
+/**
+ * Measures the line-height as it is actually rendered (in CSS pixels) for the
+ * given element.
+ *
+ * On iOS Safari, fractional `line-height` values are floored to integer pixels
+ * at paint time, which makes `getComputedStyle(...).lineHeight` and the
+ * `1lh` unit drift from the visual baseline. This function inserts a hidden
+ * probe element with the same font/line-height related styles, measures the
+ * total height across multiple lines, and divides by the line count to obtain
+ * the actually rendered per-line height.
+ *
+ * Returns `NaN` in non-DOM environments (SSR), or when the probe cannot be
+ * measured (no body, no defaultView, zero/negative height, or measurement
+ * exception).
+ *
+ * The caller is responsible for waiting on `document.fonts.ready` before
+ * calling this function when accurate font-loaded measurements matter.
+ *
+ * @param element - The element whose rendered line-height should be measured.
+ * @param options - Measurement options.
+ * @returns The rendered line-height in CSS pixels, or `NaN` when measurement
+ *   is not possible.
+ */
+export declare const getRenderedLineHeight: (element: HTMLElement, options?: GetRenderedLineHeightOptions) => number;

package/dist/libs/get/get-rendered-line-height.es.js

@@ -0,0 +1,57 @@
+const DEFAULT_SAMPLE_LINES = 20;
+const MIN_SAMPLE_LINES = 2;
+const MAX_SAMPLE_LINES = 100;
+const normalizeSampleLines = (value) => {
+  const raw = value ?? DEFAULT_SAMPLE_LINES;
+  if (!Number.isFinite(raw)) return DEFAULT_SAMPLE_LINES;
+  return Math.min(MAX_SAMPLE_LINES, Math.max(MIN_SAMPLE_LINES, Math.floor(raw)));
+};
+const getRenderedLineHeight = (element, options) => {
+  if (typeof window === "undefined") return Number.NaN;
+  const sampleLines = normalizeSampleLines(options?.sampleLines);
+  const ownerDocument = element.ownerDocument;
+  const host = ownerDocument?.body;
+  const view = ownerDocument?.defaultView;
+  if (!host || !view) return Number.NaN;
+  const cs = view.getComputedStyle(element);
+  const probe = ownerDocument.createElement("div");
+  const style = probe.style;
+  style.position = "absolute";
+  style.left = "-9999px";
+  style.top = "0";
+  style.visibility = "hidden";
+  style.pointerEvents = "none";
+  style.margin = "0";
+  style.padding = "0";
+  style.border = "0";
+  style.whiteSpace = "pre";
+  style.fontFamily = cs.fontFamily;
+  style.fontSize = cs.fontSize;
+  style.fontWeight = cs.fontWeight;
+  style.fontStyle = cs.fontStyle;
+  style.lineHeight = cs.lineHeight;
+  style.letterSpacing = cs.letterSpacing;
+  style.fontFeatureSettings = cs.fontFeatureSettings;
+  if (cs.fontVariationSettings) {
+    style.fontVariationSettings = cs.fontVariationSettings;
+  }
+  for (let i = 0; i < sampleLines; i++) {
+    if (i > 0) probe.appendChild(ownerDocument.createElement("br"));
+    probe.appendChild(ownerDocument.createTextNode("X"));
+  }
+  host.appendChild(probe);
+  try {
+    const probeHeight = probe.getBoundingClientRect().height;
+    if (probeHeight <= 0) return Number.NaN;
+    return probeHeight / sampleLines;
+  } catch {
+    return Number.NaN;
+  } finally {
+    if (probe.parentNode === host) {
+      host.removeChild(probe);
+    }
+  }
+};
+export {
+  getRenderedLineHeight
+};

package/dist/libs/get/get-rendered-line-height.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/libs/get/get-scrollbar-width.cjs.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const getScrollbarWidth = () => window.innerWidth - document.body.clientWidth;
+const getScrollbarWidth = () => window.innerWidth - document.documentElement.clientWidth;
 exports.getScrollbarWidth = getScrollbarWidth;

package/dist/libs/get/get-scrollbar-width.d.ts

@@ -1,6 +1,9 @@
 /**
  * Retrieves the width of the scrollbar.
  *
+ * Uses document.documentElement.clientWidth instead of document.body.clientWidth
+ * to ensure accurate measurement regardless of body element styling (e.g., max-width, margin).
+ *
  * @returns {number} The width of the scrollbar in pixels.
  */
 export declare const getScrollbarWidth: () => number;

package/dist/libs/get/get-scrollbar-width.es.js

@@ -1,4 +1,4 @@
-const getScrollbarWidth = () => window.innerWidth - document.body.clientWidth;
+const getScrollbarWidth = () => window.innerWidth - document.documentElement.clientWidth;
 export {
   getScrollbarWidth
 };

package/dist/libs/get/get-ua-data.cjs.js

@@ -11,11 +11,11 @@ const getUaData = () => {
   const osName = result.os.name;
   const type = result.device.type;
   const uaString = {
-    browserName: browserName ? browserName.toLowerCase().replace(" ", "-") : "",
+    browserName: browserName ? browserName.toLowerCase().replace(/ /g, "-") : "",
     browserVersion: browserVersion ? browserVersion : "",
-    browserEngine: browserEngine ? browserEngine.toLowerCase().replace(" ", "-") : "",
-    osName: osName ? osName.toLowerCase().replace(" ", "-") : "",
-    type: typeof type !== "undefined" ? type.toLowerCase().replace(" ", "-") : "laptop",
+    browserEngine: browserEngine ? browserEngine.toLowerCase().replace(/ /g, "-") : "",
+    osName: osName ? osName.toLowerCase().replace(/ /g, "-") : "",
+    type: typeof type !== "undefined" ? type.toLowerCase().replace(/ /g, "-") : "laptop",
     touchSupport: isTouchSupport.isTouchSupport()
   };
   return uaString;

package/dist/libs/get/get-ua-data.es.js

@@ -9,11 +9,11 @@ const getUaData = () => {
   const osName = result.os.name;
   const type = result.device.type;
   const uaString = {
-    browserName: browserName ? browserName.toLowerCase().replace(" ", "-") : "",
+    browserName: browserName ? browserName.toLowerCase().replace(/ /g, "-") : "",
     browserVersion: browserVersion ? browserVersion : "",
-    browserEngine: browserEngine ? browserEngine.toLowerCase().replace(" ", "-") : "",
-    osName: osName ? osName.toLowerCase().replace(" ", "-") : "",
-    type: typeof type !== "undefined" ? type.toLowerCase().replace(" ", "-") : "laptop",
+    browserEngine: browserEngine ? browserEngine.toLowerCase().replace(/ /g, "-") : "",
+    osName: osName ? osName.toLowerCase().replace(/ /g, "-") : "",
+    type: typeof type !== "undefined" ? type.toLowerCase().replace(/ /g, "-") : "laptop",
     touchSupport: isTouchSupport()
   };
   return uaString;

package/dist/libs/get/index.cjs.js

@@ -9,9 +9,10 @@ const getGravatarUrl = require("./get-gravatar-url.cjs.js");
 const getOrientation = require("./get-orientation.cjs.js");
 const getParentList = require("./get-parent-list.cjs.js");
 const getQueryParams = require("./get-query-params.cjs.js");
-const getRelativeTime = require("./get-relative-time.cjs.js");
 const getRandomInt = require("./get-random-int.cjs.js");
+const getRelativeTime = require("./get-relative-time.cjs.js");
 const getRem = require("./get-rem.cjs.js");
+const getRenderedLineHeight = require("./get-rendered-line-height.cjs.js");
 const getScrollbarWidth = require("./get-scrollbar-width.cjs.js");
 const getSessionStorage = require("./get-session-storage.cjs.js");
 const getStringLength = require("./get-string-length.cjs.js");
@@ -27,9 +28,10 @@ exports.getGravatarUrl = getGravatarUrl.getGravatarUrl;
 exports.getOrientation = getOrientation.getOrientation;
 exports.getParentList = getParentList.getParentList;
 exports.getQueryParams = getQueryParams.getQueryParams;
-exports.getRelativeTime = getRelativeTime.getRelativeTime;
 exports.getRandomInt = getRandomInt.getRandomInt;
+exports.getRelativeTime = getRelativeTime.getRelativeTime;
 exports.getRem = getRem.getRem;
+exports.getRenderedLineHeight = getRenderedLineHeight.getRenderedLineHeight;
 exports.getScrollbarWidth = getScrollbarWidth.getScrollbarWidth;
 exports.getSessionStorage = getSessionStorage.getSessionStorage;
 exports.getStringLength = getStringLength.getStringLength;

package/dist/libs/get/index.d.ts

@@ -10,9 +10,10 @@ export * from './get-gravatar-url';
 export * from './get-orientation';
 export * from './get-parent-list';
 export * from './get-query-params';
-export * from './get-relative-time';
 export * from './get-random-int';
+export * from './get-relative-time';
 export * from './get-rem';
+export * from './get-rendered-line-height';
 export * from './get-scrollbar-width';
 export * from './get-session-storage';
 export * from './get-string-length';

package/dist/libs/get/index.es.js

@@ -7,9 +7,10 @@ import { getGravatarUrl } from "./get-gravatar-url.es.js";
 import { getOrientation } from "./get-orientation.es.js";
 import { getParentList } from "./get-parent-list.es.js";
 import { getQueryParams } from "./get-query-params.es.js";
-import { getRelativeTime } from "./get-relative-time.es.js";
 import { getRandomInt } from "./get-random-int.es.js";
+import { getRelativeTime } from "./get-relative-time.es.js";
 import { getRem } from "./get-rem.es.js";
+import { getRenderedLineHeight } from "./get-rendered-line-height.es.js";
 import { getScrollbarWidth } from "./get-scrollbar-width.es.js";
 import { getSessionStorage } from "./get-session-storage.es.js";
 import { getStringLength } from "./get-string-length.es.js";
@@ -29,6 +30,7 @@ export {
   getRandomInt,
   getRelativeTime,
   getRem,
+  getRenderedLineHeight,
   getScrollbarWidth,
   getSessionStorage,
   getStringLength,

package/dist/libs/is/is-after-date-time.cjs.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const dayjs = require("dayjs");
 const isAfterDateTime = (dateA, now = dayjs()) => {
+  if (!dayjs(dateA).isValid()) {
+    throw new Error("dateA is not a valid date");
+  }
   return now.isAfter(dayjs(dateA), "millisecond");
 };
 exports.isAfterDateTime = isAfterDateTime;

package/dist/libs/is/is-after-date-time.d.ts

@@ -6,5 +6,6 @@ import { default as dayjs } from 'dayjs';
  * @param dateA - A date/time string to compare, parsed with dayjs.
  * @param now - Optional reference time as a Dayjs object; defaults to current time.
  * @returns `true` if `now` is strictly after the parsed `dateA` at millisecond precision; otherwise `false`.
+ * @throws Will throw an error if dateA is not a valid date.
  */
 export declare const isAfterDateTime: (dateA: string, now?: dayjs.Dayjs) => boolean;

package/dist/libs/is/is-after-date-time.es.js

@@ -1,5 +1,8 @@
 import dayjs from "dayjs";
 const isAfterDateTime = (dateA, now = dayjs()) => {
+  if (!dayjs(dateA).isValid()) {
+    throw new Error("dateA is not a valid date");
+  }
   return now.isAfter(dayjs(dateA), "millisecond");
 };
 export {

package/dist/libs/is/is-in-viewport.cjs.js

@@ -5,7 +5,7 @@ const parseRootMargin = (rootMargin) => {
   const parseValue = (value) => {
     if (value.endsWith("%")) {
       const percent = Number.parseFloat(value) / 100;
-      return window.innerHeight * percent;
+      return window.innerWidth * percent;
     }
     return Number.parseFloat(value) || 0;
   };

package/dist/libs/is/is-in-viewport.es.js

@@ -3,7 +3,7 @@ const parseRootMargin = (rootMargin) => {
   const parseValue = (value) => {
     if (value.endsWith("%")) {
       const percent = Number.parseFloat(value) / 100;
-      return window.innerHeight * percent;
+      return window.innerWidth * percent;
     }
     return Number.parseFloat(value) || 0;
   };

package/dist/libs/is/is-ipad.cjs.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const getOrientation = require("../get/get-orientation.cjs.js");
 const getUaData = require("../get/get-ua-data.cjs.js");
 const isIpad = (orientation = "portrait") => {
+  if (typeof window === "undefined" || typeof navigator === "undefined") {
+    return false;
+  }
   const clientData = getUaData.getUaData();
   if (!clientData.touchSupport) return false;
   return clientData.type === "laptop" && clientData.osName === "mac-os" && clientData.browserName === "safari" && getOrientation.getOrientation() === orientation;

package/dist/libs/is/is-ipad.d.ts

@@ -4,6 +4,7 @@ type Orientation = 'portrait' | 'landscape';
  *
  * @param orientation - The desired screen orientation ('portrait' or 'landscape'). Defaults to 'portrait'.
  * @returns `true` if the device is an iPad with the specified orientation, otherwise `false`.
+ * Returns `false` in SSR environments where window/navigator is undefined.
  */
 export declare const isIpad: (orientation?: Orientation) => boolean;
 export {};

package/dist/libs/is/is-ipad.es.js

@@ -1,6 +1,9 @@
 import { getOrientation } from "../get/get-orientation.es.js";
 import { getUaData } from "../get/get-ua-data.es.js";
 const isIpad = (orientation = "portrait") => {
+  if (typeof window === "undefined" || typeof navigator === "undefined") {
+    return false;
+  }
   const clientData = getUaData();
   if (!clientData.touchSupport) return false;
   return clientData.type === "laptop" && clientData.osName === "mac-os" && clientData.browserName === "safari" && getOrientation() === orientation;

package/dist/libs/security/html-sanitize.cjs.js

@@ -4,4 +4,6 @@ const DOMPurify = require("isomorphic-dompurify");
 const htmlSanitize = (html, config = {}) => {
   return DOMPurify.sanitize(html, config);
 };
+const sanitizeHtml = htmlSanitize;
 exports.htmlSanitize = htmlSanitize;
+exports.sanitizeHtml = sanitizeHtml;

package/dist/libs/security/html-sanitize.d.ts

@@ -7,3 +7,12 @@ import { default as DOMPurify } from 'isomorphic-dompurify';
  * @returns The sanitized HTML string.
  */
 export declare const htmlSanitize: (html: string, config?: Parameters<typeof DOMPurify.sanitize>[1]) => string;
+/**
+ * Alias for htmlSanitize.
+ * Sanitizes the given HTML string to prevent XSS attacks.
+ *
+ * @param html - The HTML string to sanitize.
+ * @param config - Optional configuration for DOMPurify.
+ * @returns The sanitized HTML string.
+ */
+export declare const sanitizeHtml: (html: string, config?: Parameters<typeof DOMPurify.sanitize>[1]) => string;

package/dist/libs/security/html-sanitize.es.js

@@ -2,6 +2,8 @@ import DOMPurify from "isomorphic-dompurify";
 const htmlSanitize = (html, config = {}) => {
   return DOMPurify.sanitize(html, config);
 };
+const sanitizeHtml = htmlSanitize;
 export {
-  htmlSanitize
+  htmlSanitize,
+  sanitizeHtml
 };

package/dist/libs/security/index.cjs.js

@@ -2,3 +2,4 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const htmlSanitize = require("./html-sanitize.cjs.js");
 exports.htmlSanitize = htmlSanitize.htmlSanitize;
+exports.sanitizeHtml = htmlSanitize.sanitizeHtml;

package/dist/libs/security/index.es.js

@@ -1,4 +1,5 @@
-import { htmlSanitize } from "./html-sanitize.es.js";
+import { htmlSanitize, sanitizeHtml } from "./html-sanitize.es.js";
 export {
-  htmlSanitize
+  htmlSanitize,
+  sanitizeHtml
 };

package/dist/libs/transform/wrap-text-with-spans.cjs.js

@@ -1,13 +1,15 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const runes2 = require("runes2");
 const wrapTextWithSpans = (element) => {
   if (!element) return;
   if (element.nodeType === Node.TEXT_NODE) {
     const textContent = (element.textContent || "").trim();
     const fragment = document.createDocumentFragment();
-    for (const char of textContent) {
+    const graphemes = runes2.runes(textContent);
+    for (const grapheme of graphemes) {
       const span = document.createElement("span");
-      span.textContent = char;
+      span.textContent = grapheme;
       fragment.appendChild(span);
     }
     element.replaceWith(fragment);

package/dist/libs/transform/wrap-text-with-spans.d.ts

@@ -1,10 +1,15 @@
 /**
- * Wraps each character of the text content of an HTML element with individual <span> elements.
+ * Wraps each grapheme cluster (visual character) of the text content of an HTML element with individual <span> elements.
  *
  * @param element - The HTML element whose text content will be wrapped with <span> elements.
  *
  * This function recursively processes the given element and its child nodes. If the node is a text node,
- * it replaces the text content with a series of <span> elements, each containing a single character from the text.
+ * it replaces the text content with a series of <span> elements, each containing a single grapheme cluster from the text.
  * If the node is an element node, it recursively processes its child nodes.
+ *
+ * This function correctly handles:
+ * - Composite emojis (e.g., 👨‍👩‍👧‍👦, 👍🏻)
+ * - Flag emojis (e.g., 🇯🇵)
+ * - Combined characters
  */
 export declare const wrapTextWithSpans: (element: HTMLElement) => void;

package/dist/libs/transform/wrap-text-with-spans.es.js

@@ -1,11 +1,13 @@
+import { runes } from "runes2";
 const wrapTextWithSpans = (element) => {
   if (!element) return;
   if (element.nodeType === Node.TEXT_NODE) {
     const textContent = (element.textContent || "").trim();
     const fragment = document.createDocumentFragment();
-    for (const char of textContent) {
+    const graphemes = runes(textContent);
+    for (const grapheme of graphemes) {
       const span = document.createElement("span");
-      span.textContent = char;
+      span.textContent = grapheme;
       fragment.appendChild(span);
     }
     element.replaceWith(fragment);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umaki",
-  "version": "0.10.1",
+  "version": "0.13.0",
   "description": "A utility that is often used in web production.",
   "author": "TsubasaHiga",
   "homepage": "https://github.com/TsubasaHiga/umaki",