@pisell/utils 3.0.5 → 3.0.7

package/es/select/types.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Select 组件公共类型定义
+ * 供 PisellSingleSelect、PisellMultipleSelect 等组件使用
+ */
+import React from 'react';
+export type { DisplayState } from '../common';
+/**
+ * 选项基础类型
+ * @template T 选项值的类型，默认为 string | number
+ */
+export interface SelectOption<T = string | number> {
+    /**
+     * 选项值（唯一标识）
+     */
+    value: T;
+    /**
+     * 选项显示文本
+     */
+    label: string;
+    /**
+     * 是否禁用该选项
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 选项图标（可选）
+     */
+    icon?: React.ReactNode;
+    /**
+     * 标签背景色（多选时用于自定义标签颜色）
+     * @example '#61dafb'
+     */
+    color?: string;
+}
+/**
+ * 选项过滤函数类型
+ * @template T 选项值的类型
+ * @param input 用户输入的搜索文本
+ * @param option 当前选项对象
+ * @returns 是否保留该选项
+ */
+export declare type FilterOptionFunc<T = string | number> = (input: string, option: SelectOption<T>) => boolean;
+/**
+ * 排序方向
+ */
+export declare type SortDirection = 'asc' | 'desc';
+/**
+ * Select 状态 Hook 返回值（单选）
+ * @template T 值的类型
+ */
+export interface SelectState<T = string | number> {
+    /**
+     * 当前选中值
+     */
+    value: T | null | undefined;
+    /**
+     * 设置选中值
+     */
+    setValue: (value: T | null) => void;
+    /**
+     * 清空选中值
+     */
+    clearValue: () => void;
+}
+/**
+ * Multiple Select 状态 Hook 返回值（多选）
+ * @template T 值的类型
+ */
+export interface MultipleSelectState<T = string | number> {
+    /**
+     * 当前选中值数组
+     */
+    value: T[];
+    /**
+     * 设置选中值数组
+     */
+    setValue: (value: T[]) => void;
+    /**
+     * 添加一个选中值
+     */
+    addValue: (value: T) => void;
+    /**
+     * 移除一个选中值
+     */
+    removeValue: (value: T) => void;
+    /**
+     * 清空所有选中值
+     */
+    clearValue: () => void;
+}
+/**
+ * 标签显示信息（多选专用）
+ * @template T 选项值的类型
+ */
+export interface TagDisplayInfo<T = string | number> {
+    /**
+     * 可见的标签列表
+     */
+    visibleTags: SelectOption<T>[];
+    /**
+     * 隐藏的标签列表
+     */
+    hiddenTags: SelectOption<T>[];
+    /**
+     * 隐藏的标签数量
+     */
+    hiddenCount: number;
+}
+/**
+ * useSelectState Hook 的配置选项（单选）
+ * @template T 值的类型
+ */
+export interface UseSelectStateOptions<T = string | number> {
+    /**
+     * 受控模式：当前值
+     */
+    value?: T | null;
+    /**
+     * 非受控模式：默认值
+     */
+    defaultValue?: T;
+    /**
+     * 值变化回调
+     */
+    onChange?: (value: T | null, option: SelectOption<T> | null) => void;
+    /**
+     * 模式（用于类型区分）
+     */
+    mode: 'single';
+}
+/**
+ * useMultipleSelectState Hook 的配置选项（多选）
+ * @template T 值的类型
+ */
+export interface UseMultipleSelectStateOptions<T = string | number> {
+    /**
+     * 受控模式：当前值数组
+     */
+    value?: T[];
+    /**
+     * 非受控模式：默认值数组
+     */
+    defaultValue?: T[];
+    /**
+     * 值变化回调
+     */
+    onChange?: (value: T[], options: SelectOption<T>[]) => void;
+    /**
+     * 模式（用于类型区分）
+     */
+    mode: 'multiple';
+}
+/**
+ * 基础 Select Props（公共属性）
+ * @template T 值的类型
+ */
+export interface BaseSelectProps<T = string | number> {
+    /**
+     * 选项列表（必填）
+     */
+    options: SelectOption<T>[];
+    /**
+     * 占位符文本
+     * @default '请选择'
+     */
+    placeholder?: string;
+    /**
+     * 是否显示搜索框
+     * @default false
+     */
+    showSearch?: boolean;
+    /**
+     * 是否显示清空按钮
+     * @default false
+     */
+    allowClear?: boolean;
+    /**
+     * 是否禁用
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 是否只读
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * 尺寸
+     * @default 'middle'
+     */
+    size?: 'small' | 'middle' | 'large';
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: React.CSSProperties;
+    /**
+     * 标签文本
+     */
+    label?: string;
+    /**
+     * 辅助提示文本
+     */
+    helperText?: string;
+    /**
+     * 是否必填
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * 是否显示错误状态
+     * @default false
+     */
+    error?: boolean;
+    /**
+     * 错误提示文本
+     */
+    errorText?: string;
+    /**
+     * 是否启用过滤
+     * @default false
+     */
+    filterable?: boolean;
+    /**
+     * 自定义过滤函数
+     */
+    filterOption?: FilterOptionFunc<T>;
+    /**
+     * 是否启用排序
+     * @default false
+     */
+    sortable?: boolean;
+    /**
+     * 排序方向
+     */
+    sortDirection?: SortDirection;
+    /**
+     * 搜索输入回调
+     */
+    onSearch?: (value: string) => void;
+    /**
+     * 获得焦点回调
+     */
+    onFocus?: (event: React.FocusEvent) => void;
+    /**
+     * 失去焦点回调
+     */
+    onBlur?: (event: React.FocusEvent) => void;
+    /**
+     * 下拉框显隐回调
+     */
+    onDropdownVisibleChange?: (visible: boolean) => void;
+}

package/es/select/types.js

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

package/es/select/utils/filterOptions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 选项过滤工具函数
+ */
+import type { SelectOption, FilterOptionFunc } from '../types';
+/**
+ * 默认的选项过滤函数
+ * 根据 label 进行模糊匹配（不区分大小写）
+ * @template T 选项值的类型
+ * @param input 搜索输入文本
+ * @param option 选项对象
+ * @returns 是否保留该选项
+ */
+export declare function defaultFilterOption<T = string | number>(input: string, option: SelectOption<T>): boolean;
+/**
+ * 过滤选项列表
+ * @template T 选项值的类型
+ * @param options 原始选项列表
+ * @param searchText 搜索文本
+ * @param filterFunc 自定义过滤函数（可选）
+ * @returns 过滤后的选项列表
+ */
+export declare function filterOptions<T = string | number>(options: SelectOption<T>[], searchText: string, filterFunc?: FilterOptionFunc<T>): SelectOption<T>[];

package/es/select/utils/filterOptions.js

@@ -0,0 +1,34 @@
+/**
+ * 选项过滤工具函数
+ */
+
+/**
+ * 默认的选项过滤函数
+ * 根据 label 进行模糊匹配（不区分大小写）
+ * @template T 选项值的类型
+ * @param input 搜索输入文本
+ * @param option 选项对象
+ * @returns 是否保留该选项
+ */
+export function defaultFilterOption(input, option) {
+  if (!input) return true;
+  var searchText = input.toLowerCase();
+  var labelText = option.label.toLowerCase();
+  return labelText.includes(searchText);
+}
+
+/**
+ * 过滤选项列表
+ * @template T 选项值的类型
+ * @param options 原始选项列表
+ * @param searchText 搜索文本
+ * @param filterFunc 自定义过滤函数（可选）
+ * @returns 过滤后的选项列表
+ */
+export function filterOptions(options, searchText, filterFunc) {
+  if (!searchText) return options;
+  var filterFn = filterFunc || defaultFilterOption;
+  return options.filter(function (opt) {
+    return filterFn(searchText, opt);
+  });
+}

package/es/select/utils/helpers.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Select 组件辅助函数
+ */
+import type { SelectOption } from '../types';
+/**
+ * 根据值查找选项对象
+ * @template T 选项值的类型
+ * @param value 选项值
+ * @param options 选项列表
+ * @returns 找到的选项对象，如果没找到返回 undefined
+ */
+export declare function findOptionByValue<T = string | number>(value: T, options: SelectOption<T>[]): SelectOption<T> | undefined;
+/**
+ * 根据值数组查找选项对象数组
+ * @template T 选项值的类型
+ * @param values 选项值数组
+ * @param options 选项列表
+ * @returns 找到的选项对象数组
+ */
+export declare function findOptionsByValues<T = string | number>(values: T[], options: SelectOption<T>[]): SelectOption<T>[];
+/**
+ * 判断选项是否被选中（单选）
+ * @template T 选项值的类型
+ * @param optionValue 选项值
+ * @param selectedValue 当前选中值
+ * @returns 是否选中
+ */
+export declare function isOptionSelected<T = string | number>(optionValue: T, selectedValue: T | null | undefined): boolean;
+/**
+ * 判断选项是否被选中（多选）
+ * @template T 选项值的类型
+ * @param optionValue 选项值
+ * @param selectedValues 当前选中值数组
+ * @returns 是否选中
+ */
+export declare function isOptionSelectedInMultiple<T = string | number>(optionValue: T, selectedValues: T[]): boolean;
+/**
+ * 生成唯一 ID
+ * @param prefix ID 前缀
+ * @returns 唯一 ID
+ */
+export declare function generateId(prefix?: string): string;

package/es/select/utils/helpers.js

@@ -0,0 +1,61 @@
+/**
+ * Select 组件辅助函数
+ */
+
+/**
+ * 根据值查找选项对象
+ * @template T 选项值的类型
+ * @param value 选项值
+ * @param options 选项列表
+ * @returns 找到的选项对象，如果没找到返回 undefined
+ */
+export function findOptionByValue(value, options) {
+  return options.find(function (opt) {
+    return opt.value === value;
+  });
+}
+
+/**
+ * 根据值数组查找选项对象数组
+ * @template T 选项值的类型
+ * @param values 选项值数组
+ * @param options 选项列表
+ * @returns 找到的选项对象数组
+ */
+export function findOptionsByValues(values, options) {
+  return values.map(function (val) {
+    return findOptionByValue(val, options);
+  }).filter(Boolean);
+}
+
+/**
+ * 判断选项是否被选中（单选）
+ * @template T 选项值的类型
+ * @param optionValue 选项值
+ * @param selectedValue 当前选中值
+ * @returns 是否选中
+ */
+export function isOptionSelected(optionValue, selectedValue) {
+  return selectedValue !== null && selectedValue !== undefined && optionValue === selectedValue;
+}
+
+/**
+ * 判断选项是否被选中（多选）
+ * @template T 选项值的类型
+ * @param optionValue 选项值
+ * @param selectedValues 当前选中值数组
+ * @returns 是否选中
+ */
+export function isOptionSelectedInMultiple(optionValue, selectedValues) {
+  return selectedValues.includes(optionValue);
+}
+
+/**
+ * 生成唯一 ID
+ * @param prefix ID 前缀
+ * @returns 唯一 ID
+ */
+export function generateId() {
+  var prefix = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'select';
+  return "".concat(prefix, "-").concat(Math.random().toString(36).substr(2, 9));
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Select 工具函数导出
+ */
+export { calculateTagDisplay } from './tagAggregation';
+export { filterOptions, defaultFilterOption } from './filterOptions';
+export { sortOptions } from './sortOptions';
+export { findOptionByValue, findOptionsByValues, isOptionSelected, isOptionSelectedInMultiple, generateId, } from './helpers';

package/es/select/utils/index.js

@@ -0,0 +1,8 @@
+/**
+ * Select 工具函数导出
+ */
+
+export { calculateTagDisplay } from "./tagAggregation";
+export { filterOptions, defaultFilterOption } from "./filterOptions";
+export { sortOptions } from "./sortOptions";
+export { findOptionByValue, findOptionsByValues, isOptionSelected, isOptionSelectedInMultiple, generateId } from "./helpers";

package/es/select/utils/sortOptions.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 选项排序工具函数
+ */
+import type { SelectOption, SortDirection } from '../types';
+/**
+ * 排序选项列表
+ * @template T 选项值的类型
+ * @param options 原始选项列表
+ * @param direction 排序方向（'asc' 升序 | 'desc' 降序）
+ * @returns 排序后的选项列表（新数组）
+ */
+export declare function sortOptions<T = string | number>(options: SelectOption<T>[], direction?: SortDirection): SelectOption<T>[];

package/es/select/utils/sortOptions.js

@@ -0,0 +1,32 @@
+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 _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 _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 _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; }
+/**
+ * 选项排序工具函数
+ */
+
+/**
+ * 排序选项列表
+ * @template T 选项值的类型
+ * @param options 原始选项列表
+ * @param direction 排序方向（'asc' 升序 | 'desc' 降序）
+ * @returns 排序后的选项列表（新数组）
+ */
+export function sortOptions(options) {
+  var direction = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'asc';
+  // 创建副本避免修改原数组
+  var sortedOptions = _toConsumableArray(options);
+  sortedOptions.sort(function (a, b) {
+    var labelA = a.label.toLowerCase();
+    var labelB = b.label.toLowerCase();
+    if (direction === 'asc') {
+      return labelA.localeCompare(labelB);
+    } else {
+      return labelB.localeCompare(labelA);
+    }
+  });
+  return sortedOptions;
+}

package/es/select/utils/tagAggregation.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 标签聚合工具函数
+ * 用于多选下拉组件的标签显示逻辑
+ */
+import type { SelectOption, TagDisplayInfo } from '../types';
+/**
+ * 计算需要显示的标签和聚合信息
+ * @template T 选项值的类型
+ * @param selectedValues 当前选中的值数组
+ * @param options 所有选项列表
+ * @param maxTagCount 最多显示的标签数量
+ * @returns 标签显示信息
+ *
+ * @example
+ * ```tsx
+ * const tagInfo = calculateTagDisplay(['a', 'b', 'c', 'd'], options, 2);
+ * // 返回：
+ * // {
+ * //   visibleTags: [option_a, option_b],
+ * //   hiddenTags: [option_c, option_d],
+ * //   hiddenCount: 2
+ * // }
+ * ```
+ */
+export declare function calculateTagDisplay<T = string | number>(selectedValues: T[], options: SelectOption<T>[], maxTagCount: number): TagDisplayInfo<T>;

package/es/select/utils/tagAggregation.js

@@ -0,0 +1,48 @@
+/**
+ * 标签聚合工具函数
+ * 用于多选下拉组件的标签显示逻辑
+ */
+
+/**
+ * 计算需要显示的标签和聚合信息
+ * @template T 选项值的类型
+ * @param selectedValues 当前选中的值数组
+ * @param options 所有选项列表
+ * @param maxTagCount 最多显示的标签数量
+ * @returns 标签显示信息
+ * 
+ * @example
+ * ```tsx
+ * const tagInfo = calculateTagDisplay(['a', 'b', 'c', 'd'], options, 2);
+ * // 返回：
+ * // {
+ * //   visibleTags: [option_a, option_b],
+ * //   hiddenTags: [option_c, option_d],
+ * //   hiddenCount: 2
+ * // }
+ * ```
+ */
+export function calculateTagDisplay(selectedValues, options, maxTagCount) {
+  // 根据选中值找到对应的选项对象
+  var selectedOptions = selectedValues.map(function (v) {
+    return options.find(function (opt) {
+      return opt.value === v;
+    });
+  }).filter(Boolean);
+
+  // 如果选中数量不超过 maxTagCount，全部显示
+  if (selectedOptions.length <= maxTagCount) {
+    return {
+      visibleTags: selectedOptions,
+      hiddenTags: [],
+      hiddenCount: 0
+    };
+  }
+
+  // 否则进行聚合
+  return {
+    visibleTags: selectedOptions.slice(0, maxTagCount),
+    hiddenTags: selectedOptions.slice(maxTagCount),
+    hiddenCount: selectedOptions.length - maxTagCount
+  };
+}

package/es/text-input/hooks/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 文本输入 Hooks 导出
+ */
+export { useTextInputState } from './useTextInputState';

package/es/text-input/hooks/index.js

@@ -0,0 +1,5 @@
+/**
+ * 文本输入 Hooks 导出
+ */
+
+export { useTextInputState } from "./useTextInputState";

package/es/text-input/hooks/useTextInputState.d.ts

@@ -0,0 +1,24 @@
+import type { BaseTextInputProps, TextInputState } from '../types';
+/**
+ * 文本输入状态管理 Hook
+ *
+ * 管理组件的内部状态，包括：
+ * - 值管理（受控/非受控模式）
+ * - 校验状态管理
+ * - 事件处理函数封装
+ *
+ * 支持受控和非受控两种模式：
+ * - 受控模式：value 由外部传入，组件不维护内部状态
+ * - 非受控模式：使用 defaultValue，组件维护内部状态
+ *
+ * @param props 组件 Props（包含校验配置）
+ * @returns 文本输入状态对象
+ *
+ * @example
+ * // 受控模式
+ * const state = useTextInputState({ value: 'hello', onChange: (v) => console.log(v) });
+ *
+ * // 非受控模式
+ * const state = useTextInputState({ defaultValue: 'hello' });
+ */
+export declare function useTextInputState(props: BaseTextInputProps): TextInputState;