@lipemat/js-helpers 1.0.0

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@lipemat/js-helpers",
+  "version": "1.0.0",
+  "description": "Framework-agnostic TypeScript helper utilities used across @lipemat projects",
+  "author": "Mat Lipe",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.21.1"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "helpers",
+    "utilities",
+    "typescript",
+    "debounce",
+    "throttle",
+    "memoize"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lipemat/js-helpers.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lipemat/js-helpers/issues"
+  },
+  "homepage": "https://github.com/lipemat/js-helpers#readme",
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint ./src --fix --cache",
+    "postinstall": "test -f ./dev/bin/npm-post-install && bash ./dev/bin/npm-post-install || true",
+    "prepublishOnly": "rm -rf dist/* && yarn run build",
+    "test": "jest",
+    "validate-ts": "tsc --noEmit",
+    "watch": "tsc --watch"
+  },
+  "dependencies": {
+    "dompurify": "^3.4.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.28.5",
+    "@babel/preset-env": "^7.28.5",
+    "@babel/preset-typescript": "^7.28.5",
+    "@lipemat/eslint-config": "^5.2.0",
+    "@testing-library/dom": "^10.4.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.19.3",
+    "babel-jest": "^30.2.0",
+    "eslint": "^9",
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "packageManager": "yarn@4.17.0"
+}

package/src/classes/Readme.md

@@ -0,0 +1,28 @@
+# classes
+
+Utilities for manipulating CSS class name strings.
+
+## Exports
+
+### `classNameAmend( existing, className, add ): string`
+
+Add or remove a single class name from a space-separated string of classes. Duplicates are removed.
+
+- `existing: string | undefined` — current class string.
+- `className: string` — class to add or remove.
+- `add: boolean` — `true` to add, `false` to remove.
+
+### `sanitizeCssModuleClass( className ): string`
+
+Normalize a CSS class name produced by a PHP CSS module: trims whitespace, converts inner spaces to dots, and ensures a leading dot. Returns `''` for `null`.
+
+## Usage
+
+```ts
+import {classNameAmend, sanitizeCssModuleClass} from '@lipemat/js-helpers';
+
+classNameAmend( 'a b', 'c', true ); // 'a b c'
+classNameAmend( 'a b c', 'b', false ); // 'a c'
+
+sanitizeCssModuleClass( 'card active' ); // '.card.active'
+```

package/src/classes/classes.ts

@@ -0,0 +1,51 @@
+/**
+ * Utility functions for manipulating CSS class names.
+ *
+ * @version 1.4.0
+ */
+
+
+/**
+ * Add or remove a className from an existing string of classes.
+ *
+ * @param {string}  existing  - String of existing classes to work with.
+ * @param {string}  className - Classname to add or remove
+ * @param {boolean} add       - Either add or remove the class.
+ *
+ * @return {string} - The modified string of classes.
+ */
+export function classNameAmend( existing: string | undefined, className: string, add: boolean ): string {
+	let classes: string[] = [];
+	if ( undefined !== existing ) {
+		classes = existing.split( ' ' );
+	}
+	if ( add ) {
+		classes.push( className );
+	} else {
+		classes = classes.filter( _class => _class !== className );
+	}
+	return [ ...new Set( classes ) ].join( ' ' );
+}
+
+/**
+ * Sanitize a CSS class name provided by PHP CSS module.
+ *
+ * - Removes any leading or trailing whitespace.
+ * - Replaces any spaces with a single dot.
+ * - Adds a leading dot if not present.
+ *
+ * @param {string} className - The class name to sanitize.
+ *
+ * @return {string} - The sanitized class name.
+ */
+export function sanitizeCssModuleClass( className: string | null ): string {
+	if ( null === className ) {
+		return '';
+	}
+	className = className.trim();
+	className = className.replace( /\s+/g, '.' );
+	if ( className.charAt( 0 ) !== '.' ) {
+		className = '.' + className;
+	}
+	return className;
+}

package/src/colors/Readme.md

@@ -0,0 +1,28 @@
+# colors
+
+Convert between hex and RGB color formats and measure perceived lightness.
+
+## Exports
+
+### `hexToRGB( hex, alpha? ): string`
+
+Convert a hex color to an `rgb()` string, or `rgba()` when `alpha` is provided. Non-hex input is returned unchanged.
+
+### `RGBToHex( rgb ): string`
+
+Convert an `rgb()`/`rgba()` string to a hex color. Input already starting with `#` is returned unchanged. Returns `''` if it cannot be parsed.
+
+### `getLightness( hexOrRGB ): number`
+
+Return the relative luminance of a hex or `rgb()` color as a number between `0` and `1`. `> 0.5` is light, `<= 0.5` is dark.
+
+## Usage
+
+```ts
+import {hexToRGB, RGBToHex, getLightness} from '@lipemat/js-helpers';
+
+hexToRGB( '#fff' ); // 'rgb(255, 255, 255)'
+hexToRGB( '#000', 0.5 ); // 'rgba(0, 0, 0, 0.5)'
+RGBToHex( 'rgb(255, 255, 255)' ); // '#ffffff'
+getLightness( '#ffffff' ); // 1
+```

package/src/colors/colors.ts

@@ -0,0 +1,80 @@
+/**
+ * Color Utilities
+ *
+ * @version 1.2.0
+ */
+
+export function hexToRGB( hex: string, alpha?: number ): string {
+	if ( '#' !== hex[ 0 ] ) {
+		return hex;
+	}
+	const {r, g, b} = convertHexToRGB( hex );
+
+	if ( typeof alpha !== 'undefined' ) {
+		return 'rgba(' + r + ', ' + g + ', ' + b + ', ' + alpha + ')';
+	}
+	return 'rgb(' + r + ', ' + g + ', ' + b + ')';
+}
+
+
+export function RGBToHex( rgb: string ): string {
+	if ( '#' === rgb[ 0 ] ) {
+		return rgb;
+	}
+	const colors = rgb.match(
+		/^rgba?[\s+]?\([\s+]?(\d+)[\s+]?,[\s+]?(\d+)[\s+]?,[\s+]?(\d+)[\s+]?/i,
+	);
+	return ( colors !== null ) && 4 === colors.length
+		? '#' +
+		( '0' + parseInt( colors[ 1 ], 10 ).toString( 16 ) ).slice( -2 ) +
+		( '0' + parseInt( colors[ 2 ], 10 ).toString( 16 ) ).slice( -2 ) +
+		( '0' + parseInt( colors[ 3 ], 10 ).toString( 16 ) ).slice( -2 )
+		: '';
+}
+
+/**
+ * Get the lightness of a color.
+ *
+ * > 0.5 is light, <= 0.5 is dark.
+ */
+export function getLightness( hexOrRGB: string ): number {
+	const {r, g, b} = convertHexToRGB( hexOrRGB );
+	return Number( ( ( ( 0.2126 * r ) + ( 0.7152 * g ) + ( 0.0722 * b ) ) / 255 ).toFixed( 2 ) );
+}
+
+
+function convertHexToRGB( hex: string ): { r: number, b: number, g: number } {
+	// Already RGB, just convert to object.
+	if ( hex.startsWith( 'rgb(' ) ) {
+		const colors = hex.match(
+			/^rgba?\(\s*(?<r>\d+)\s*,\s*(?<g>\d+)\s*,\s(?<b>\d+)(?:\s*,\s*[\d.]+)?\s*\)$/i,
+		);
+		const groups = colors?.groups;
+		return {
+			r: parseInt( groups?.r ?? '0', 10 ),
+			g: parseInt( groups?.g ?? '0', 10 ),
+			b: parseInt( groups?.b ?? '0', 10 ),
+		};
+	}
+
+
+	if ( 4 === hex.length ) {
+		let colors = hex.substring( 1 ).split( '' );
+		colors = [
+			colors[ 0 ],
+			colors[ 0 ],
+			colors[ 1 ],
+			colors[ 1 ],
+			colors[ 2 ],
+			colors[ 2 ],
+		];
+		hex = colors.join( '' );
+	}
+
+	const r = parseInt( hex.slice( 1, 3 ), 16 ),
+		g = parseInt( hex.slice( 3, 5 ), 16 ),
+		b = parseInt( hex.slice( 5, 7 ), 16 );
+
+
+	return {r, g, b};
+}

package/src/csvExport/Readme.md

@@ -0,0 +1,35 @@
+# csvExport
+
+Generate a CSV file in the browser and trigger a download. HTML entities in the data are decoded and values are sanitized with [DOMPurify](https://github.com/cure53/DOMPurify).
+
+## Exports
+
+### `csvExport( data, fileName ): void`
+
+Build a CSV from `data` and prompt the browser to download it as `fileName`.
+
+- `data: CsvData` — an array of row objects (keys become headers) or an array of arrays (no header row).
+- `fileName: string` — download file name.
+
+### `CsvData` (type)
+
+```ts
+type CsvData = Array<{ [ column: string ]: number | string } | Array<number | string>>;
+```
+
+## Usage
+
+```ts
+import {csvExport, type CsvData} from '@lipemat/js-helpers';
+
+const data: CsvData = [
+	{name: 'Jane', email: 'jane@example.com'},
+	{name: 'John', email: 'john@example.com'},
+];
+
+csvExport( data, 'users.csv' );
+```
+
+## Notes
+
+Requires a DOM (`document`, `Blob`, `URL.createObjectURL`); intended for browser use.

package/src/csvExport/csvExport.ts

@@ -0,0 +1,89 @@
+import DOMPurify from 'dompurify';
+
+const {sanitize} = DOMPurify;
+
+/**
+ * @version 1.0.8
+ */
+
+export type CsvData = Array<{ [ column: string ]: number | string } | Array<number | string>>
+
+/**
+ * Generate a csv file and trigger a download of a said file.
+ *
+ * @author Mat Lipe
+ * @since September, 2019
+ *
+ * @param {Array<Object>} data
+ * @param {string}        fileName
+ *
+ * @return {void}
+ */
+export function csvExport( data: CsvData, fileName: string ): void {
+	const csv = convertArrayOfObjectsToCSV( data );
+	if ( null === csv ) {
+		return;
+	}
+
+	const blob = new Blob( [ csv ], {type: 'text/csv;charset=utf-8;'} );
+	const link = document.createElement( 'a' );
+
+	if ( link.download !== undefined ) {
+		link.setAttribute( 'href', sanitize( URL.createObjectURL( blob ) ) );
+		link.setAttribute( 'download', sanitize( fileName ) );
+		link.style.visibility = 'hidden';
+		document.body.appendChild( link );
+		link.click();
+		document.body.removeChild( link );
+	}
+}
+
+/**
+ * Convert an array of objects|array to a string representation of a csv file.
+ *
+ * @param data
+ */
+function convertArrayOfObjectsToCSV( data: CsvData ): string | null {
+	if ( null === data || ( 0 === data.length ) ) {
+		return null;
+	}
+
+	const keys: string[] = Object.keys( data[ 0 ] );
+
+	let result = '';
+	if ( '0' !== keys[ 0 ] ) {
+		result += keys.join( ',' );
+		result += '\n';
+	}
+
+	data.forEach( item => {
+		keys.forEach( ( key: string, i: number ) => {
+			if ( i > 0 ) {
+				result += ',';
+			}
+			// @ts-expect-error
+			let innerValue = item[ key ]?.toString().replace( /"/g, '""' ) ?? '';
+			if ( innerValue.search( /([",\n])/g ) >= 0 ) {
+				innerValue = '"' + innerValue + '"';
+			}
+			result += decodeHtml( innerValue );
+		} );
+		result += '\n';
+	} );
+
+	return result;
+}
+
+/**
+ * Convert any HTML special characters to their string version,
+ * so they may be encoded via `encodeURI`.
+ *
+ * @param {string} html
+ *
+ * @return {string}
+ */
+function decodeHtml( html: string ): string {
+	const txt = document.createElement( 'textarea' );
+	txt.innerHTML = sanitize( html );
+	return txt.value;
+}

package/src/date/Readme.md

@@ -0,0 +1,21 @@
+# date
+
+Format a `Date` object using a small set of tokens.
+
+## Exports
+
+### `getFormattedDate( date, format? ): string`
+
+Return `date` formatted using the `format` string. Supported tokens are `mm` (month), `dd` (day), and `yyyy` (year). Defaults to `'mm/dd/yyyy'`.
+
+- `date: Date` — the date to format.
+- `format?: string` — token string, defaults to `'mm/dd/yyyy'`.
+
+## Usage
+
+```ts
+import {getFormattedDate} from '@lipemat/js-helpers';
+
+getFormattedDate( new Date( 2023, 0, 5 ) ); // '01/05/2023'
+getFormattedDate( new Date( 2023, 0, 5 ), 'yyyy-mm-dd' ); // '2023-01-05'
+```

package/src/date/date.ts

@@ -0,0 +1,23 @@
+/**
+ * @version 1.1.0
+ */
+
+/**
+ * Given a Date object, return the date in the provided format.
+ * Limited to `mm`, `dd`, and `yyyy` formats.
+ *
+ */
+export function getFormattedDate( date: Date, format: string = 'mm/dd/yyyy' ): string {
+	const year = date.getFullYear();
+
+	let month = ( 1 + date.getMonth() ).toString();
+	month = month.length > 1 ? month : '0' + month;
+
+	let day = date.getDate().toString();
+	day = day.length > 1 ? day : '0' + day;
+
+	return format
+		.replace( 'mm', month )
+		.replace( 'dd', day )
+		.replace( 'yyyy', year.toString() );
+}

package/src/debounce/Readme.md

@@ -0,0 +1,27 @@
+# debounce
+
+Lodash-free debounce. Delays calling `fn` until `wait` ms have passed since the last call, returning a promise that resolves with the result.
+
+## Exports
+
+### `debounce( fn, wait? )`
+
+- `fn: T` — function to debounce.
+- `wait?: number` — delay in milliseconds, defaults to `300`.
+
+Returns a debounced function that resolves a `Promise` with the result, plus:
+
+- `.immediate( ...args )` — run `fn` right away, bypassing the wait.
+- `.cancel()` — cancel a pending call.
+
+## Usage
+
+```ts
+import {debounce} from '@lipemat/js-helpers';
+
+const save = debounce( ( value: string ) => persist( value ), 500 );
+
+await save( 'hello' ); // resolves after 500ms of inactivity
+save.immediate( 'now' ); // runs synchronously
+save.cancel(); // cancel a pending call
+```

package/src/debounce/debounce.ts

@@ -0,0 +1,47 @@
+import type {Callback, Return} from '../once/once.js';
+
+type Result<T extends Callback> = {
+	( ...args: Parameters<T> ): Promise<ReturnType<T>>;
+	immediate: ( ...args: Parameters<T> ) => ReturnType<T>;
+	cancel: () => void;
+};
+
+
+/**
+ * Alternative to lodash debounce.
+ *
+ * - Additional support for `immediate` execution to bypass the wait time.
+ * - Returns a promise to allow waiting for a completion of the debounced function.
+ *
+ * @version 1.4.1
+ */
+export function debounce<T extends Callback>( fn: T, wait = 300 ): Result<T> {
+	let timer: number | NodeJS.Timeout;
+	let promise: Promise<ReturnType<T>> | null = null;
+	let resolve: ( value: ReturnType<T> ) => void;
+
+	const debounced = function( ...args: Parameters<T> ): Promise<ReturnType<T>> {
+		clearTimeout( timer );
+		timer = setTimeout( () => {
+			resolve( fn( ...args ) );
+		}, wait );
+
+		return promise ??= new Promise<ReturnType<T>>( res => {
+			resolve = res;
+		} );
+	};
+
+	// Immediate execution method.
+	debounced.immediate = function( ...args: Parameters<T> ): Return<T> {
+		clearTimeout( timer );
+		return fn( ...args );
+	};
+
+	// Cancel method.
+	debounced.cancel = function() {
+		clearTimeout( timer );
+		promise = null;
+	};
+
+	return debounced as Result<T>;
+}

package/src/delay/Readme.md

@@ -0,0 +1,20 @@
+# delay
+
+Resolve a promise after a given amount of time. Useful for letting transitions finish while other work happens.
+
+## Exports
+
+### `delay( ms ): Promise<void>`
+
+- `ms: number` — milliseconds to wait before resolving.
+
+## Usage
+
+```ts
+import {delay} from '@lipemat/js-helpers';
+
+const delayPromise = delay( 200 );
+// Do other work while waiting.
+await fetchPosts();
+await delayPromise;
+```

package/src/delay/delay.ts

@@ -0,0 +1,19 @@
+/**
+ * Delay a promise by a given amount of time.
+ *
+ * Used to provide enough time to show transitions while
+ * other operations are happening.
+ *
+ * @example ```ts
+ *     const delayPromise = delay(200);
+ *     // Do another action while waiting for the delay.
+ *     await fetchPosts();
+ *     await delayPromise;
+ *
+ * @param  ms The amount of time to delay the promise by.
+ *
+ * @version 1.0.0
+ */
+export const delay = ( ms: number ): Promise<void> => {
+	return new Promise( resolve => setTimeout( resolve, ms ) );
+};

package/src/device/Readme.md

@@ -0,0 +1,31 @@
+# device
+
+Detect whether the current client is a desktop or mobile device. Modeled after WordPress' `wp_is_mobile()` but evaluated client-side so it works with edge page caching and user-agent emulation.
+
+## Exports
+
+### `isDesktop(): boolean`
+
+`true` when the viewport is wider than 800px and the user agent is not mobile.
+
+### `isMobile(): boolean`
+
+`true` when the viewport is 800px or narrower, or the user agent is mobile.
+
+### `hasMobileUserAgent(): boolean`
+
+`true` when `navigator.userAgentData.mobile` is set, or the `navigator.userAgent` string matches a known mobile identifier.
+
+## Usage
+
+```ts
+import {isDesktop, isMobile, hasMobileUserAgent} from '@lipemat/js-helpers';
+
+if ( isMobile() ) {
+	// Render the compact layout.
+}
+```
+
+## Notes
+
+Requires `window` and `navigator`; intended for browser use.

package/src/device/device.ts

@@ -0,0 +1,46 @@
+const breakPoint = 800;
+
+
+/**
+ * Detects if the user is on a desktop or mobile device.
+ * - Desktop: Width greater than 800 px and not a mobile user agent.
+ * - Mobile: Width less than 800 px or a mobile user agent.
+ *
+ * @see useMobile - For keeping track of mobile state in React components.
+ *
+ * @version 2.0.2
+ */
+
+
+export function isDesktop(): boolean {
+	return window.innerWidth > breakPoint && ! hasMobileUserAgent();
+}
+
+export function isMobile(): boolean {
+	return window.innerWidth < breakPoint || hasMobileUserAgent();
+}
+
+/**
+ * Checks if the user agent is a mobile device.
+ * - Checks if an HTTPS `userAgentData` API is available and if the `mobile` property is true.
+ * - If not available, checks the `navigator.userAgent` string for common mobile identifiers.
+ *
+ * Modeled after the `wp_is_mobile()` function in WordPress but runs on the client side
+ * to support:
+ *  1. Edge page caching.
+ *  2. Changes in emulation of the user agent during development.
+ *
+ * @link https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgentData
+ * @link https://developer.wordpress.org/reference/functions/wp_is_mobile/
+ */
+export function hasMobileUserAgent(): boolean {
+	const ua = navigator.userAgent;
+	// @ts-expect-error TS2551 -- Not all browsers support userAgentData yet.
+	const uaData = navigator.userAgentData ?? undefined;
+	if ( 'undefined' !== typeof uaData && 'undefined' !== typeof uaData.mobile && Boolean( uaData.mobile ) ) {
+		return true;
+	} else if ( 'undefined' === typeof ua || '' === ua ) {
+		return false;
+	}
+	return [ 'Mobile', 'Android', 'Silk/', 'Kindle', 'BlackBerry', 'Opera Mini', 'Opera Mobi' ].some( agent => ua.includes( agent ) );
+}

package/src/dom-ready/Readme.md

@@ -0,0 +1,27 @@
+# dom-ready
+
+Run a callback once the document has finished parsing. Logic borrowed from `@wordpress/dom-ready`.
+
+## Exports
+
+### `domReady( callback ): void`
+
+Execute `callback` after `DOMContentLoaded`. If the document is already `interactive` or `complete`, the callback runs immediately. Does nothing when `document` is undefined (e.g. server-side).
+
+- `callback: EventCallback` — function to run when the DOM is ready.
+
+### `EventCallback` (type)
+
+```ts
+type EventCallback = ( this: Document | void, ev?: Event ) => void;
+```
+
+## Usage
+
+```ts
+import {domReady} from '@lipemat/js-helpers';
+
+domReady( () => {
+	console.log( 'DOM is ready' );
+} );
+```

package/src/dom-ready/dom-ready.ts

@@ -0,0 +1,22 @@
+export type EventCallback = ( this: Document | void, ev?: Event ) => void;
+
+
+/**
+ * Fire a callback after the DOMContentLoaded event.
+ * If called after the document is loaded, callback will be executed immediately.
+ * Logic borrowed from `@wordpress/dom-ready`.
+ *
+ * @param {Function} callback Callback to execute.
+ *
+ * @version 1.0.0
+ */
+export function domReady( callback: EventCallback ) {
+	if ( 'undefined' === typeof document ) {
+		return;
+	}
+	if ( 'complete' === document.readyState || 'interactive' === document.readyState ) {
+		return void callback();
+	}
+
+	document.addEventListener( 'DOMContentLoaded', () => callback() );
+}