@tanwan/utils 1.1.0 → 1.2.0

package/dist/scrollToElement.cjs

@@ -0,0 +1,23 @@
+//#region src/dom/scrollToElement/index.ts
+/**
+* 平滑滚动到指定元素
+*
+* @param el - 目标 DOM 元素
+* @param options - ScrollIntoView 选项，默认 `{ behavior: 'smooth', block: 'start' }`
+*
+* @example
+* ```ts
+* import scrollToElement from '@tanwan/utils/scrollToElement'
+* scrollToElement(document.getElementById('section2'))
+* scrollToElement(el, { behavior: 'instant', block: 'center' })
+* ```
+*/
+function scrollToElement(el, options) {
+	el.scrollIntoView({
+		behavior: "smooth",
+		block: "start",
+		...options
+	});
+}
+//#endregion
+module.exports = scrollToElement;

package/dist/scrollToElement.d.cts

@@ -0,0 +1,16 @@
+//#region src/dom/scrollToElement/index.d.ts
+/**
+* 平滑滚动到指定元素
+*
+* @param el - 目标 DOM 元素
+* @param options - ScrollIntoView 选项，默认 `{ behavior: 'smooth', block: 'start' }`
+*
+* @example
+* ```ts
+* import scrollToElement from '@tanwan/utils/scrollToElement'
+* scrollToElement(document.getElementById('section2'))
+* scrollToElement(el, { behavior: 'instant', block: 'center' })
+* ```
+*/
+declare function scrollToElement(el: Element, options?: ScrollIntoViewOptions): void;
+export = scrollToElement;

package/dist/scrollToElement.d.ts

@@ -0,0 +1,17 @@
+//#region src/dom/scrollToElement/index.d.ts
+/**
+* 平滑滚动到指定元素
+*
+* @param el - 目标 DOM 元素
+* @param options - ScrollIntoView 选项，默认 `{ behavior: 'smooth', block: 'start' }`
+*
+* @example
+* ```ts
+* import scrollToElement from '@tanwan/utils/scrollToElement'
+* scrollToElement(document.getElementById('section2'))
+* scrollToElement(el, { behavior: 'instant', block: 'center' })
+* ```
+*/
+declare function scrollToElement(el: Element, options?: ScrollIntoViewOptions): void;
+//#endregion
+export { scrollToElement as default };

package/dist/scrollToElement.js

@@ -0,0 +1,23 @@
+//#region src/dom/scrollToElement/index.ts
+/**
+* 平滑滚动到指定元素
+*
+* @param el - 目标 DOM 元素
+* @param options - ScrollIntoView 选项，默认 `{ behavior: 'smooth', block: 'start' }`
+*
+* @example
+* ```ts
+* import scrollToElement from '@tanwan/utils/scrollToElement'
+* scrollToElement(document.getElementById('section2'))
+* scrollToElement(el, { behavior: 'instant', block: 'center' })
+* ```
+*/
+function scrollToElement(el, options) {
+	el.scrollIntoView({
+		behavior: "smooth",
+		block: "start",
+		...options
+	});
+}
+//#endregion
+export { scrollToElement as default };

package/dist/setCssVar.cjs

@@ -0,0 +1,22 @@
+//#region src/dom/setCssVar/index.ts
+/**
+* 设置 CSS 自定义属性（CSS 变量）
+*
+* @param name - CSS 变量名（可带 `--` 前缀或省略）
+* @param value - CSS 变量值
+* @param el - 指定元素，不传则设置到 `document.documentElement`（`:root`）
+*
+* @example
+* ```ts
+* import setCssVar from '@tanwan/utils/setCssVar'
+* setCssVar('--color-primary', '#ff0000')
+* setCssVar('color-primary', '#ff0000')   // 自动补 -- 前缀
+* setCssVar('--bg', 'dark', el)
+* ```
+*/
+function setCssVar(name, value, el = document.documentElement) {
+	const varName = name.startsWith("--") ? name : `--${name}`;
+	el.style.setProperty(varName, value);
+}
+//#endregion
+module.exports = setCssVar;

package/dist/setCssVar.d.cts

@@ -0,0 +1,18 @@
+//#region src/dom/setCssVar/index.d.ts
+/**
+* 设置 CSS 自定义属性（CSS 变量）
+*
+* @param name - CSS 变量名（可带 `--` 前缀或省略）
+* @param value - CSS 变量值
+* @param el - 指定元素，不传则设置到 `document.documentElement`（`:root`）
+*
+* @example
+* ```ts
+* import setCssVar from '@tanwan/utils/setCssVar'
+* setCssVar('--color-primary', '#ff0000')
+* setCssVar('color-primary', '#ff0000')   // 自动补 -- 前缀
+* setCssVar('--bg', 'dark', el)
+* ```
+*/
+declare function setCssVar(name: string, value: string, el?: HTMLElement): void;
+export = setCssVar;

package/dist/setCssVar.d.ts

@@ -0,0 +1,19 @@
+//#region src/dom/setCssVar/index.d.ts
+/**
+* 设置 CSS 自定义属性（CSS 变量）
+*
+* @param name - CSS 变量名（可带 `--` 前缀或省略）
+* @param value - CSS 变量值
+* @param el - 指定元素，不传则设置到 `document.documentElement`（`:root`）
+*
+* @example
+* ```ts
+* import setCssVar from '@tanwan/utils/setCssVar'
+* setCssVar('--color-primary', '#ff0000')
+* setCssVar('color-primary', '#ff0000')   // 自动补 -- 前缀
+* setCssVar('--bg', 'dark', el)
+* ```
+*/
+declare function setCssVar(name: string, value: string, el?: HTMLElement): void;
+//#endregion
+export { setCssVar as default };

package/dist/setCssVar.js

@@ -0,0 +1,22 @@
+//#region src/dom/setCssVar/index.ts
+/**
+* 设置 CSS 自定义属性（CSS 变量）
+*
+* @param name - CSS 变量名（可带 `--` 前缀或省略）
+* @param value - CSS 变量值
+* @param el - 指定元素，不传则设置到 `document.documentElement`（`:root`）
+*
+* @example
+* ```ts
+* import setCssVar from '@tanwan/utils/setCssVar'
+* setCssVar('--color-primary', '#ff0000')
+* setCssVar('color-primary', '#ff0000')   // 自动补 -- 前缀
+* setCssVar('--bg', 'dark', el)
+* ```
+*/
+function setCssVar(name, value, el = document.documentElement) {
+	const varName = name.startsWith("--") ? name : `--${name}`;
+	el.style.setProperty(varName, value);
+}
+//#endregion
+export { setCssVar as default };

package/dist/setStorage.cjs

@@ -0,0 +1,25 @@
+//#region src/storage/setStorage/index.ts
+/**
+* 安全地将值序列化为 JSON 并写入 localStorage
+*
+* @param key - 存储键名
+* @param value - 要存储的值
+* @returns 是否写入成功
+*
+* @example
+* ```ts
+* import setStorage from '@tanwan/utils/setStorage'
+* setStorage('user', { name: 'Alice' })
+* // localStorage.getItem('user') → '{"name":"Alice"}'
+* ```
+*/
+function setStorage(key, value) {
+	try {
+		localStorage.setItem(key, JSON.stringify(value));
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+module.exports = setStorage;

package/dist/setStorage.d.cts

@@ -0,0 +1,17 @@
+//#region src/storage/setStorage/index.d.ts
+/**
+* 安全地将值序列化为 JSON 并写入 localStorage
+*
+* @param key - 存储键名
+* @param value - 要存储的值
+* @returns 是否写入成功
+*
+* @example
+* ```ts
+* import setStorage from '@tanwan/utils/setStorage'
+* setStorage('user', { name: 'Alice' })
+* // localStorage.getItem('user') → '{"name":"Alice"}'
+* ```
+*/
+declare function setStorage(key: string, value: unknown): boolean;
+export = setStorage;

package/dist/setStorage.d.ts

@@ -0,0 +1,18 @@
+//#region src/storage/setStorage/index.d.ts
+/**
+* 安全地将值序列化为 JSON 并写入 localStorage
+*
+* @param key - 存储键名
+* @param value - 要存储的值
+* @returns 是否写入成功
+*
+* @example
+* ```ts
+* import setStorage from '@tanwan/utils/setStorage'
+* setStorage('user', { name: 'Alice' })
+* // localStorage.getItem('user') → '{"name":"Alice"}'
+* ```
+*/
+declare function setStorage(key: string, value: unknown): boolean;
+//#endregion
+export { setStorage as default };

package/dist/setStorage.js

@@ -0,0 +1,25 @@
+//#region src/storage/setStorage/index.ts
+/**
+* 安全地将值序列化为 JSON 并写入 localStorage
+*
+* @param key - 存储键名
+* @param value - 要存储的值
+* @returns 是否写入成功
+*
+* @example
+* ```ts
+* import setStorage from '@tanwan/utils/setStorage'
+* setStorage('user', { name: 'Alice' })
+* // localStorage.getItem('user') → '{"name":"Alice"}'
+* ```
+*/
+function setStorage(key, value) {
+	try {
+		localStorage.setItem(key, JSON.stringify(value));
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { setStorage as default };

package/dist/setStyle.cjs

@@ -0,0 +1,22 @@
+//#region src/dom/setStyle/index.ts
+/**
+* 批量设置元素行内样式
+*
+* @param el - DOM 元素
+* @param styles - 样式对象，属性名为 camelCase
+*
+* @example
+* ```ts
+* import setStyle from '@tanwan/utils/setStyle'
+* setStyle(el, {
+*   width: '100px',
+*   height: '200px',
+*   backgroundColor: 'red',
+* })
+* ```
+*/
+function setStyle(el, styles) {
+	for (const key of Object.keys(styles)) el.style[key] = String(styles[key]);
+}
+//#endregion
+module.exports = setStyle;

package/dist/setStyle.d.cts

@@ -0,0 +1,19 @@
+//#region src/dom/setStyle/index.d.ts
+/**
+* 批量设置元素行内样式
+*
+* @param el - DOM 元素
+* @param styles - 样式对象，属性名为 camelCase
+*
+* @example
+* ```ts
+* import setStyle from '@tanwan/utils/setStyle'
+* setStyle(el, {
+*   width: '100px',
+*   height: '200px',
+*   backgroundColor: 'red',
+* })
+* ```
+*/
+declare function setStyle(el: HTMLElement, styles: Record<string, string | number>): void;
+export = setStyle;

package/dist/setStyle.d.ts

@@ -0,0 +1,20 @@
+//#region src/dom/setStyle/index.d.ts
+/**
+* 批量设置元素行内样式
+*
+* @param el - DOM 元素
+* @param styles - 样式对象，属性名为 camelCase
+*
+* @example
+* ```ts
+* import setStyle from '@tanwan/utils/setStyle'
+* setStyle(el, {
+*   width: '100px',
+*   height: '200px',
+*   backgroundColor: 'red',
+* })
+* ```
+*/
+declare function setStyle(el: HTMLElement, styles: Record<string, string | number>): void;
+//#endregion
+export { setStyle as default };

package/dist/setStyle.js

@@ -0,0 +1,22 @@
+//#region src/dom/setStyle/index.ts
+/**
+* 批量设置元素行内样式
+*
+* @param el - DOM 元素
+* @param styles - 样式对象，属性名为 camelCase
+*
+* @example
+* ```ts
+* import setStyle from '@tanwan/utils/setStyle'
+* setStyle(el, {
+*   width: '100px',
+*   height: '200px',
+*   backgroundColor: 'red',
+* })
+* ```
+*/
+function setStyle(el, styles) {
+	for (const key of Object.keys(styles)) el.style[key] = String(styles[key]);
+}
+//#endregion
+export { setStyle as default };

package/dist/{array/shuffle.d.cts → shuffle.d.cts}

@@ -8,5 +8,4 @@
 * ```
 */
 declare function shuffle<T>(arr: T[]): T[];
-export = shuffle;
-//# sourceMappingURL=shuffle.d.cts.map
+export = shuffle;

package/dist/{array/shuffle.d.ts → shuffle.d.ts}

@@ -9,5 +9,4 @@
 */
 declare function shuffle<T>(arr: T[]): T[];
 //#endregion
-export { shuffle as default };
-//# sourceMappingURL=shuffle.d.ts.map
+export { shuffle as default };

package/dist/{array/shuffle.js → shuffle.js}

@@ -17,5 +17,3 @@ function shuffle(arr) {
 }
 //#endregion
 export { shuffle as default };
-
-//# sourceMappingURL=shuffle.js.map

package/dist/snakeCase.cjs

@@ -0,0 +1,18 @@
+//#region src/string/snakeCase/index.ts
+/**
+* 将字符串转换为蛇形命名（snake_case）
+*
+* @example
+* ```ts
+* import snakeCase from '@tanwan/utils/snakeCase'
+* snakeCase('fooBar')     // 'foo_bar'
+* snakeCase('FooBarBaz')  // 'foo_bar_baz'
+* snakeCase('foo-bar')    // 'foo_bar'
+* snakeCase('foo bar')    // 'foo_bar'
+* ```
+*/
+function snakeCase(str) {
+	return str.replace(/[A-Z]/g, (letter, index) => index === 0 ? letter : "_" + letter).replace(/[-_\s]+/g, "_").toLowerCase();
+}
+//#endregion
+module.exports = snakeCase;

package/dist/snakeCase.d.cts

@@ -0,0 +1,15 @@
+//#region src/string/snakeCase/index.d.ts
+/**
+* 将字符串转换为蛇形命名（snake_case）
+*
+* @example
+* ```ts
+* import snakeCase from '@tanwan/utils/snakeCase'
+* snakeCase('fooBar')     // 'foo_bar'
+* snakeCase('FooBarBaz')  // 'foo_bar_baz'
+* snakeCase('foo-bar')    // 'foo_bar'
+* snakeCase('foo bar')    // 'foo_bar'
+* ```
+*/
+declare function snakeCase(str: string): string;
+export = snakeCase;

package/dist/snakeCase.d.ts

@@ -0,0 +1,16 @@
+//#region src/string/snakeCase/index.d.ts
+/**
+* 将字符串转换为蛇形命名（snake_case）
+*
+* @example
+* ```ts
+* import snakeCase from '@tanwan/utils/snakeCase'
+* snakeCase('fooBar')     // 'foo_bar'
+* snakeCase('FooBarBaz')  // 'foo_bar_baz'
+* snakeCase('foo-bar')    // 'foo_bar'
+* snakeCase('foo bar')    // 'foo_bar'
+* ```
+*/
+declare function snakeCase(str: string): string;
+//#endregion
+export { snakeCase as default };

package/dist/snakeCase.js

@@ -0,0 +1,18 @@
+//#region src/string/snakeCase/index.ts
+/**
+* 将字符串转换为蛇形命名（snake_case）
+*
+* @example
+* ```ts
+* import snakeCase from '@tanwan/utils/snakeCase'
+* snakeCase('fooBar')     // 'foo_bar'
+* snakeCase('FooBarBaz')  // 'foo_bar_baz'
+* snakeCase('foo-bar')    // 'foo_bar'
+* snakeCase('foo bar')    // 'foo_bar'
+* ```
+*/
+function snakeCase(str) {
+	return str.replace(/[A-Z]/g, (letter, index) => index === 0 ? letter : "_" + letter).replace(/[-_\s]+/g, "_").toLowerCase();
+}
+//#endregion
+export { snakeCase as default };

package/dist/sortBy.cjs

@@ -0,0 +1,30 @@
+//#region src/array/sortBy/index.ts
+/**
+* 按指定属性或迭代函数对数组排序（升序）
+*
+* @param arr - 待排序数组
+* @param iteratee - 排序依据：属性名或返回排序值的函数
+* @returns 排序后的新数组
+*
+* @example
+* ```ts
+* import sortBy from '@tanwan/utils/sortBy'
+* sortBy([{ age: 30 }, { age: 20 }], 'age')
+* // [{ age: 20 }, { age: 30 }]
+*
+* sortBy(['apple', 'banana', 'cherry'], (s) => s.length)
+* // ['apple', 'cherry', 'banana']
+* ```
+*/
+function sortBy(arr, iteratee) {
+	const getValue = typeof iteratee === "function" ? iteratee : (item) => item[iteratee];
+	return [...arr].sort((a, b) => {
+		const va = getValue(a);
+		const vb = getValue(b);
+		if (va < vb) return -1;
+		if (va > vb) return 1;
+		return 0;
+	});
+}
+//#endregion
+module.exports = sortBy;

package/dist/sortBy.d.cts

@@ -0,0 +1,20 @@
+//#region src/array/sortBy/index.d.ts
+/**
+* 按指定属性或迭代函数对数组排序（升序）
+*
+* @param arr - 待排序数组
+* @param iteratee - 排序依据：属性名或返回排序值的函数
+* @returns 排序后的新数组
+*
+* @example
+* ```ts
+* import sortBy from '@tanwan/utils/sortBy'
+* sortBy([{ age: 30 }, { age: 20 }], 'age')
+* // [{ age: 20 }, { age: 30 }]
+*
+* sortBy(['apple', 'banana', 'cherry'], (s) => s.length)
+* // ['apple', 'cherry', 'banana']
+* ```
+*/
+declare function sortBy<T>(arr: T[], iteratee: keyof T | ((item: T) => number | string)): T[];
+export = sortBy;

package/dist/sortBy.d.ts

@@ -0,0 +1,21 @@
+//#region src/array/sortBy/index.d.ts
+/**
+* 按指定属性或迭代函数对数组排序（升序）
+*
+* @param arr - 待排序数组
+* @param iteratee - 排序依据：属性名或返回排序值的函数
+* @returns 排序后的新数组
+*
+* @example
+* ```ts
+* import sortBy from '@tanwan/utils/sortBy'
+* sortBy([{ age: 30 }, { age: 20 }], 'age')
+* // [{ age: 20 }, { age: 30 }]
+*
+* sortBy(['apple', 'banana', 'cherry'], (s) => s.length)
+* // ['apple', 'cherry', 'banana']
+* ```
+*/
+declare function sortBy<T>(arr: T[], iteratee: keyof T | ((item: T) => number | string)): T[];
+//#endregion
+export { sortBy as default };

package/dist/sortBy.js

@@ -0,0 +1,30 @@
+//#region src/array/sortBy/index.ts
+/**
+* 按指定属性或迭代函数对数组排序（升序）
+*
+* @param arr - 待排序数组
+* @param iteratee - 排序依据：属性名或返回排序值的函数
+* @returns 排序后的新数组
+*
+* @example
+* ```ts
+* import sortBy from '@tanwan/utils/sortBy'
+* sortBy([{ age: 30 }, { age: 20 }], 'age')
+* // [{ age: 20 }, { age: 30 }]
+*
+* sortBy(['apple', 'banana', 'cherry'], (s) => s.length)
+* // ['apple', 'cherry', 'banana']
+* ```
+*/
+function sortBy(arr, iteratee) {
+	const getValue = typeof iteratee === "function" ? iteratee : (item) => item[iteratee];
+	return [...arr].sort((a, b) => {
+		const va = getValue(a);
+		const vb = getValue(b);
+		if (va < vb) return -1;
+		if (va > vb) return 1;
+		return 0;
+	});
+}
+//#endregion
+export { sortBy as default };

package/dist/{url/stringifyQueryString.d.cts → stringifyQueryString.d.cts}

@@ -18,5 +18,4 @@
 * ```
 */
 declare function stringifyQueryString(params: Record<string, unknown>): string;
-export = stringifyQueryString;
-//# sourceMappingURL=stringifyQueryString.d.cts.map
+export = stringifyQueryString;

package/dist/{url/stringifyQueryString.d.ts → stringifyQueryString.d.ts}

@@ -19,5 +19,4 @@
 */
 declare function stringifyQueryString(params: Record<string, unknown>): string;
 //#endregion
-export { stringifyQueryString as default };
-//# sourceMappingURL=stringifyQueryString.d.ts.map
+export { stringifyQueryString as default };

package/dist/{url/stringifyQueryString.js → stringifyQueryString.js}

@@ -36,5 +36,3 @@ function stringifyQueryString(params) {
 }
 //#endregion
 export { stringifyQueryString as default };
-
-//# sourceMappingURL=stringifyQueryString.js.map

package/dist/{function/throttle.d.cts → throttle.d.cts}

@@ -10,5 +10,4 @@
 * ```
 */
 declare function throttle<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
-export = throttle;
-//# sourceMappingURL=throttle.d.cts.map
+export = throttle;

package/dist/{function/throttle.d.ts → throttle.d.ts}

@@ -11,5 +11,4 @@
 */
 declare function throttle<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
 //#endregion
-export { throttle as default };
-//# sourceMappingURL=throttle.d.ts.map
+export { throttle as default };

package/dist/{function/throttle.js → throttle.js}

@@ -26,5 +26,3 @@ function throttle(func, wait) {
 }
 //#endregion
 export { throttle as default };
-
-//# sourceMappingURL=throttle.js.map

package/dist/toggleClass.cjs

@@ -0,0 +1,22 @@
+//#region src/dom/toggleClass/index.ts
+/**
+* 切换元素的 CSS class
+*
+* @param el - DOM 元素
+* @param className - 要切换的 class
+* @param force - 可选，强制添加（true）或移除（false）
+* @returns 切换后 class 是否存在
+*
+* @example
+* ```ts
+* import toggleClass from '@tanwan/utils/toggleClass'
+* toggleClass(el, 'active')
+* toggleClass(el, 'active', true)  // 强制添加
+* toggleClass(el, 'active', false) // 强制移除
+* ```
+*/
+function toggleClass(el, className, force) {
+	return el.classList.toggle(className, force);
+}
+//#endregion
+module.exports = toggleClass;

package/dist/toggleClass.d.cts

@@ -0,0 +1,19 @@
+//#region src/dom/toggleClass/index.d.ts
+/**
+* 切换元素的 CSS class
+*
+* @param el - DOM 元素
+* @param className - 要切换的 class
+* @param force - 可选，强制添加（true）或移除（false）
+* @returns 切换后 class 是否存在
+*
+* @example
+* ```ts
+* import toggleClass from '@tanwan/utils/toggleClass'
+* toggleClass(el, 'active')
+* toggleClass(el, 'active', true)  // 强制添加
+* toggleClass(el, 'active', false) // 强制移除
+* ```
+*/
+declare function toggleClass(el: Element, className: string, force?: boolean): boolean;
+export = toggleClass;

package/dist/toggleClass.d.ts

@@ -0,0 +1,20 @@
+//#region src/dom/toggleClass/index.d.ts
+/**
+* 切换元素的 CSS class
+*
+* @param el - DOM 元素
+* @param className - 要切换的 class
+* @param force - 可选，强制添加（true）或移除（false）
+* @returns 切换后 class 是否存在
+*
+* @example
+* ```ts
+* import toggleClass from '@tanwan/utils/toggleClass'
+* toggleClass(el, 'active')
+* toggleClass(el, 'active', true)  // 强制添加
+* toggleClass(el, 'active', false) // 强制移除
+* ```
+*/
+declare function toggleClass(el: Element, className: string, force?: boolean): boolean;
+//#endregion
+export { toggleClass as default };