@pisell/utils 3.0.5 → 3.0.7

package/es/number-input/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 数值输入组件公共类型定义
+ * 供 PisellNumber、PisellCurrency、PisellPercent 等组件使用
+ */
+export type { DisplayState, ValidationResult } from '../common';
+/**
+ * 数值输入状态 Hook 返回值
+ */
+export interface NumberInputState {
+    /**
+     * 当前值
+     */
+    value: number | null | undefined;
+    /**
+     * 是否已被触摸（交互过）
+     */
+    isTouched: boolean;
+    /**
+     * 是否校验通过
+     */
+    isValid: boolean;
+    /**
+     * 错误信息数组
+     */
+    errors: string[];
+    /**
+     * 值变更处理函数
+     */
+    handleChange: (value: number | null) => void;
+    /**
+     * 失焦处理函数
+     */
+    handleBlur: () => void;
+    /**
+     * 聚焦处理函数
+     */
+    handleFocus: () => void;
+}
+/**
+ * 基础数值输入 Props（供校验和状态管理使用）
+ */
+export interface BaseNumberInputProps {
+    /**
+     * 当前值（受控）
+     */
+    value?: number | null;
+    /**
+     * 默认值（非受控）
+     */
+    defaultValue?: number | null;
+    /**
+     * 是否必填
+     */
+    required?: boolean;
+    /**
+     * 最小值
+     */
+    min?: number;
+    /**
+     * 最大值
+     */
+    max?: number;
+    /**
+     * 自定义校验函数
+     * @param value 当前值
+     * @returns true 表示通过，false 或错误信息字符串表示不通过
+     */
+    validator?: (value: number | null) => boolean | string;
+    /**
+     * 校验触发时机
+     * - onChange: 输入时即时校验
+     * - onBlur: 失焦时校验
+     * - both: 输入和失焦时都校验
+     */
+    validateTrigger?: 'onChange' | 'onBlur' | 'both';
+    /**
+     * 自定义错误提示信息
+     */
+    errorMessage?: string;
+    /**
+     * 值变更回调
+     */
+    onChange?: (value: number | null) => void;
+    /**
+     * 失焦回调
+     */
+    onBlur?: (value: number | null) => void;
+    /**
+     * 聚焦回调
+     */
+    onFocus?: () => void;
+    /**
+     * 校验回调
+     */
+    onValidate?: (isValid: boolean, errors: string[]) => void;
+}

package/es/number-input/types.js

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

package/es/number-input/utils/formatter.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 数值格式化工具函数
+ */
+/**
+ * 格式化选项
+ */
+export interface NumberFormatOptions {
+    /** 小数精度 */
+    precision?: number;
+    /** 是否使用千分位分隔符 */
+    useGrouping?: boolean;
+    /** 自定义格式化函数 */
+    formatter?: (value: number | null) => string;
+}
+/**
+ * 格式化数值
+ *
+ * @param value 数值
+ * @param options 格式化选项
+ * @returns 格式化后的字符串，null 时返回 null
+ *
+ * @example
+ * formatNumber(1234.567, { precision: 2, useGrouping: true })
+ * // 返回: "1,234.57"
+ *
+ * @example
+ * formatNumber(1234, { precision: 0, useGrouping: true })
+ * // 返回: "1,234"
+ */
+export declare function formatNumber(value: number | null | undefined, options?: NumberFormatOptions): string | null;
+/**
+ * 添加千分位分隔符
+ *
+ * @param value 数值
+ * @returns 添加千分位后的字符串
+ *
+ * @example
+ * addThousandsSeparator(1234567)
+ * // 返回: "1,234,567"
+ */
+export declare function addThousandsSeparator(value: number): string;
+/**
+ * 格式化精度
+ *
+ * @param value 数值
+ * @param precision 小数位数
+ * @returns 格式化后的数值
+ *
+ * @example
+ * formatPrecision(1.2345, 2)
+ * // 返回: 1.23
+ */
+export declare function formatPrecision(value: number, precision: number): number;

package/es/number-input/utils/formatter.js

@@ -0,0 +1,82 @@
+/**
+ * 数值格式化工具函数
+ */
+
+/**
+ * 格式化选项
+ */
+
+/**
+ * 格式化数值
+ * 
+ * @param value 数值
+ * @param options 格式化选项
+ * @returns 格式化后的字符串，null 时返回 null
+ * 
+ * @example
+ * formatNumber(1234.567, { precision: 2, useGrouping: true })
+ * // 返回: "1,234.57"
+ * 
+ * @example
+ * formatNumber(1234, { precision: 0, useGrouping: true })
+ * // 返回: "1,234"
+ */
+export function formatNumber(value) {
+  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  // 处理空值
+  if (value === null || value === undefined) {
+    return null;
+  }
+  var precision = options.precision,
+    _options$useGrouping = options.useGrouping,
+    useGrouping = _options$useGrouping === void 0 ? false : _options$useGrouping,
+    formatter = options.formatter;
+
+  // 优先使用自定义格式化函数
+  if (formatter) {
+    return formatter(value);
+  }
+
+  // 使用 toLocaleString 进行格式化
+  if (useGrouping || precision !== undefined) {
+    return value.toLocaleString('zh-CN', {
+      minimumFractionDigits: precision,
+      maximumFractionDigits: precision,
+      useGrouping: useGrouping
+    });
+  }
+
+  // 默认转字符串
+  return String(value);
+}
+
+/**
+ * 添加千分位分隔符
+ * 
+ * @param value 数值
+ * @returns 添加千分位后的字符串
+ * 
+ * @example
+ * addThousandsSeparator(1234567)
+ * // 返回: "1,234,567"
+ */
+export function addThousandsSeparator(value) {
+  return value.toLocaleString('zh-CN', {
+    useGrouping: true
+  });
+}
+
+/**
+ * 格式化精度
+ * 
+ * @param value 数值
+ * @param precision 小数位数
+ * @returns 格式化后的数值
+ * 
+ * @example
+ * formatPrecision(1.2345, 2)
+ * // 返回: 1.23
+ */
+export function formatPrecision(value, precision) {
+  return Number(value.toFixed(precision));
+}

package/es/number-input/utils/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 数值输入工具函数导出
+ */
+export { validateValue } from './validation';
+export { getDisplayState } from '../../common';
+export { formatNumber, addThousandsSeparator, formatPrecision } from './formatter';
+export type { NumberFormatOptions } from './formatter';

package/es/number-input/utils/index.js

@@ -0,0 +1,8 @@
+/**
+ * 数值输入工具函数导出
+ */
+
+export { validateValue } from "./validation";
+// getDisplayState 已移到公共模块，从 common 重新导出
+export { getDisplayState } from "../../common";
+export { formatNumber, addThousandsSeparator, formatPrecision } from "./formatter";

package/es/number-input/utils/validation.d.ts

@@ -0,0 +1,27 @@
+import type { BaseNumberInputProps, ValidationResult } from '../types';
+/**
+ * 校验数值输入
+ *
+ * 按照优先级执行校验规则：
+ * 1. 必填校验（required）
+ * 2. 最小值校验（min）
+ * 3. 最大值校验（max）
+ * 4. 自定义校验函数（validator）
+ *
+ * @param value 待校验的值
+ * @param props 校验配置
+ * @returns 校验结果对象，包含 isValid 和 errors
+ *
+ * @example
+ * validateValue(10, { required: true, min: 0, max: 100 })
+ * // { isValid: true, errors: [] }
+ *
+ * @example
+ * validateValue(null, { required: true })
+ * // { isValid: false, errors: ['此字段为必填项'] }
+ *
+ * @example
+ * validateValue(150, { min: 0, max: 100 })
+ * // { isValid: false, errors: ['不能大于 100'] }
+ */
+export declare function validateValue(value: number | null | undefined, props: BaseNumberInputProps): ValidationResult;

package/es/number-input/utils/validation.js

@@ -0,0 +1,67 @@
+/**
+ * 校验数值输入
+ * 
+ * 按照优先级执行校验规则：
+ * 1. 必填校验（required）
+ * 2. 最小值校验（min）
+ * 3. 最大值校验（max）
+ * 4. 自定义校验函数（validator）
+ * 
+ * @param value 待校验的值
+ * @param props 校验配置
+ * @returns 校验结果对象，包含 isValid 和 errors
+ * 
+ * @example
+ * validateValue(10, { required: true, min: 0, max: 100 })
+ * // { isValid: true, errors: [] }
+ * 
+ * @example
+ * validateValue(null, { required: true })
+ * // { isValid: false, errors: ['此字段为必填项'] }
+ * 
+ * @example
+ * validateValue(150, { min: 0, max: 100 })
+ * // { isValid: false, errors: ['不能大于 100'] }
+ */
+export function validateValue(value, props) {
+  var errors = [];
+
+  // 1. 必填校验
+  if (props.required && (value === null || value === undefined)) {
+    errors.push(props.errorMessage || '此字段为必填项');
+    return {
+      isValid: false,
+      errors: errors
+    };
+  }
+
+  // 如果值为空且非必填，直接返回有效
+  if (value === null || value === undefined) {
+    return {
+      isValid: true,
+      errors: errors
+    };
+  }
+
+  // 2. 最小值校验
+  if (props.min !== undefined && value < props.min) {
+    errors.push("\u4E0D\u80FD\u5C0F\u4E8E ".concat(props.min));
+  }
+
+  // 3. 最大值校验
+  if (props.max !== undefined && value > props.max) {
+    errors.push("\u4E0D\u80FD\u5927\u4E8E ".concat(props.max));
+  }
+
+  // 4. 自定义校验函数
+  if (props.validator) {
+    var result = props.validator(value);
+    if (result !== true) {
+      errors.push(typeof result === 'string' ? result : '校验失败');
+    }
+  }
+  return {
+    isValid: errors.length === 0,
+    errors: errors
+  };
+}

package/es/otherUtils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @title: 判断是否无痕模式
+ * @description:
+ * @return: *
+ * @Author: shengjie.zuo
+ * @Date: 2024-09-4 09:58:22
+ */
+export declare const detectIncognito: () => Promise<{
+    isPrivate: boolean;
+    browserName: string;
+} | {
+    isPrivate: boolean;
+}>;
+/**
+ * @Description: 生成唯一id
+ * @Author: wzw
+ * @Date: 2020-12-01 14:20:29
+ * @param {*}
+ * @return {*}
+ */
+export declare const getUniqueId: (prefix?: string, maxLength?: number) => string;
+/**
+ * @title: 对数组进行增|删
+ * @description: 用于多选选中和取消选中的处理
+ * @param {any} list
+ * @param {any} item
+ * @param {string} key
+ * @return {*}
+ * @Author: zhiwei.Wang
+ * @Date: 2023-12-19 16:44
+ */
+export declare const changeArray: <T>(list: T[] | undefined, item: T, key?: string) => T[];
+/**
+ * @title: 判断某个字段是否在列表内
+ * @description:
+ * @param {*} T
+ * @param {boolean} param2
+ * @return {*}
+ * @Author: zhiwei.Wang
+ * @Date: 2023-12-19 16:54
+ */
+export declare const getItemByArray: <T>(list: T[] | undefined, item: T, key?: string) => boolean;
+export declare const createArray: (length: number, returnItem: any) => unknown[];
+/**
+ * 根据对象内容生成唯一id
+ * @param obj
+ */
+export declare const generateUniqueIdByObj: (obj: Record<string, any>) => any;

package/es/select/hooks/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Select Hooks 导出
+ */
+export { useSelectState, useMultipleSelectState } from './useSelectState';
+export { useDebouncedSearch } from './useDebouncedSearch';

package/es/select/hooks/index.js

@@ -0,0 +1,6 @@
+/**
+ * Select Hooks 导出
+ */
+
+export { useSelectState, useMultipleSelectState } from "./useSelectState";
+export { useDebouncedSearch } from "./useDebouncedSearch";

package/es/select/hooks/useDebouncedSearch.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 防抖搜索 Hook
+ * 对用户输入进行防抖处理，避免频繁触发搜索
+ */
+/**
+ * 防抖搜索 Hook
+ * @template T 值的类型
+ * @param initialValue 初始值
+ * @param delay 防抖延迟时间（毫秒）
+ * @param callback 防抖后的回调函数
+ * @returns [防抖后的值, 设置值函数]
+ *
+ * @example
+ * ```tsx
+ * const [debouncedSearch, setSearchInput] = useDebouncedSearch('', 300, (text) => {
+ *   console.log('搜索关键词:', text);
+ * });
+ * ```
+ */
+export declare function useDebouncedSearch<T = string>(initialValue: T, delay: number, callback?: (value: T) => void): [T, (value: T) => void];

package/es/select/hooks/useDebouncedSearch.js

@@ -0,0 +1,55 @@
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+/**
+ * 防抖搜索 Hook
+ * 对用户输入进行防抖处理，避免频繁触发搜索
+ */
+
+import { useState, useEffect } from 'react';
+
+/**
+ * 防抖搜索 Hook
+ * @template T 值的类型
+ * @param initialValue 初始值
+ * @param delay 防抖延迟时间（毫秒）
+ * @param callback 防抖后的回调函数
+ * @returns [防抖后的值, 设置值函数]
+ * 
+ * @example
+ * ```tsx
+ * const [debouncedSearch, setSearchInput] = useDebouncedSearch('', 300, (text) => {
+ *   console.log('搜索关键词:', text);
+ * });
+ * ```
+ */
+export function useDebouncedSearch(initialValue, delay, callback) {
+  // 实时值（用户输入）
+  var _useState = useState(initialValue),
+    _useState2 = _slicedToArray(_useState, 2),
+    value = _useState2[0],
+    setValue = _useState2[1];
+
+  // 防抖后的值
+  var _useState3 = useState(initialValue),
+    _useState4 = _slicedToArray(_useState3, 2),
+    debouncedValue = _useState4[0],
+    setDebouncedValue = _useState4[1];
+  useEffect(function () {
+    // 创建定时器
+    var timer = setTimeout(function () {
+      setDebouncedValue(value);
+      // 触发回调
+      callback === null || callback === void 0 || callback(value);
+    }, delay);
+
+    // 清理定时器
+    return function () {
+      clearTimeout(timer);
+    };
+  }, [value, delay, callback]);
+  return [debouncedValue, setValue];
+}

package/es/select/hooks/useSelectState.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Select 状态管理 Hook
+ * 处理受控/非受控模式，适用于单选和多选
+ */
+import type { UseSelectStateOptions, UseMultipleSelectStateOptions, SelectState, MultipleSelectState } from '../types';
+/**
+ * 单选状态管理 Hook
+ * @template T 值的类型
+ * @param options Hook 配置选项
+ * @returns 状态管理对象
+ */
+export declare function useSelectState<T = string | number>(options: UseSelectStateOptions<T>): SelectState<T>;
+/**
+ * 多选状态管理 Hook
+ * @template T 值的类型
+ * @param options Hook 配置选项
+ * @returns 状态管理对象
+ */
+export declare function useMultipleSelectState<T = string | number>(options: UseMultipleSelectStateOptions<T>): MultipleSelectState<T>;

package/es/select/hooks/useSelectState.js

@@ -0,0 +1,117 @@
+function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread(); }
+function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _iterableToArray(iter) { if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter); }
+function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) return _arrayLikeToArray(arr); }
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+/**
+ * Select 状态管理 Hook
+ * 处理受控/非受控模式，适用于单选和多选
+ */
+
+import { useState, useCallback } from 'react';
+/**
+ * 单选状态管理 Hook
+ * @template T 值的类型
+ * @param options Hook 配置选项
+ * @returns 状态管理对象
+ */
+export function useSelectState(options) {
+  var controlledValue = options.value,
+    defaultValue = options.defaultValue,
+    onChange = options.onChange;
+
+  // 判断是否为受控组件
+  var isControlled = controlledValue !== undefined;
+
+  // 内部状态（非受控模式使用）
+  var _useState = useState(defaultValue !== null && defaultValue !== void 0 ? defaultValue : null),
+    _useState2 = _slicedToArray(_useState, 2),
+    internalValue = _useState2[0],
+    setInternalValue = _useState2[1];
+
+  // 当前值
+  var value = isControlled ? controlledValue : internalValue;
+
+  // 设置值
+  var setValue = useCallback(function (newValue) {
+    if (!isControlled) {
+      setInternalValue(newValue);
+    }
+    // 触发 onChange 回调
+    onChange === null || onChange === void 0 || onChange(newValue, null); // TODO: 传入对应的 option 对象
+  }, [isControlled, onChange]);
+
+  // 清空值
+  var clearValue = useCallback(function () {
+    setValue(null);
+  }, [setValue]);
+  return {
+    value: value,
+    setValue: setValue,
+    clearValue: clearValue
+  };
+}
+
+/**
+ * 多选状态管理 Hook
+ * @template T 值的类型
+ * @param options Hook 配置选项
+ * @returns 状态管理对象
+ */
+export function useMultipleSelectState(options) {
+  var controlledValue = options.value,
+    defaultValue = options.defaultValue,
+    onChange = options.onChange;
+
+  // 判断是否为受控组件
+  var isControlled = controlledValue !== undefined;
+
+  // 内部状态（非受控模式使用）
+  var _useState3 = useState(defaultValue !== null && defaultValue !== void 0 ? defaultValue : []),
+    _useState4 = _slicedToArray(_useState3, 2),
+    internalValue = _useState4[0],
+    setInternalValue = _useState4[1];
+
+  // 当前值
+  var value = isControlled ? controlledValue !== null && controlledValue !== void 0 ? controlledValue : [] : internalValue;
+
+  // 设置值
+  var setValue = useCallback(function (newValue) {
+    if (!isControlled) {
+      setInternalValue(newValue);
+    }
+    // 触发 onChange 回调
+    onChange === null || onChange === void 0 || onChange(newValue, []); // TODO: 传入对应的 options 数组
+  }, [isControlled, onChange]);
+
+  // 添加一个值
+  var addValue = useCallback(function (val) {
+    var newValue = [].concat(_toConsumableArray(value), [val]);
+    setValue(newValue);
+  }, [value, setValue]);
+
+  // 移除一个值
+  var removeValue = useCallback(function (val) {
+    var newValue = value.filter(function (v) {
+      return v !== val;
+    });
+    setValue(newValue);
+  }, [value, setValue]);
+
+  // 清空所有值
+  var clearValue = useCallback(function () {
+    setValue([]);
+  }, [setValue]);
+  return {
+    value: value,
+    setValue: setValue,
+    addValue: addValue,
+    removeValue: removeValue,
+    clearValue: clearValue
+  };
+}

package/es/select/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Select 组件相关工具和类型导出
+ * 供 PisellSingleSelect、PisellMultipleSelect 等组件使用
+ */
+export type { SelectOption, FilterOptionFunc, SortDirection, SelectState, MultipleSelectState, TagDisplayInfo, UseSelectStateOptions, UseMultipleSelectStateOptions, BaseSelectProps, } from './types';
+export { useSelectState, useMultipleSelectState } from './hooks/useSelectState';
+export { useDebouncedSearch } from './hooks/useDebouncedSearch';
+export { filterOptions, defaultFilterOption, sortOptions, calculateTagDisplay, findOptionByValue, findOptionsByValues, isOptionSelected, isOptionSelectedInMultiple, generateId, } from './utils';

package/es/select/index.js

@@ -0,0 +1,13 @@
+/**
+ * Select 组件相关工具和类型导出
+ * 供 PisellSingleSelect、PisellMultipleSelect 等组件使用
+ */
+
+// 导出所有类型
+
+// 导出 Hooks
+export { useSelectState, useMultipleSelectState } from "./hooks/useSelectState";
+export { useDebouncedSearch } from "./hooks/useDebouncedSearch";
+
+// 导出工具函数
+export { filterOptions, defaultFilterOption, sortOptions, calculateTagDisplay, findOptionByValue, findOptionsByValues, isOptionSelected, isOptionSelectedInMultiple, generateId } from "./utils";