@pisell/utils 3.0.5 → 3.0.6

package/lib/select/types.d.ts

@@ -0,0 +1,256 @@
+import { DisplayState } from "../common/types.js";
+import React from "react";
+
+//#region src/select/types.d.ts
+/**
+ * 选项基础类型
+ * @template T 选项值的类型，默认为 string | number
+ */
+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 是否保留该选项
+ */
+type FilterOptionFunc<T = string | number> = (input: string, option: SelectOption<T>) => boolean;
+/**
+ * 排序方向
+ */
+type SortDirection = 'asc' | 'desc';
+/**
+ * Select 状态 Hook 返回值（单选）
+ * @template T 值的类型
+ */
+interface SelectState<T = string | number> {
+  /**
+   * 当前选中值
+   */
+  value: T | null | undefined;
+  /**
+   * 设置选中值
+   */
+  setValue: (value: T | null) => void;
+  /**
+   * 清空选中值
+   */
+  clearValue: () => void;
+}
+/**
+ * Multiple Select 状态 Hook 返回值（多选）
+ * @template T 值的类型
+ */
+interface MultipleSelectState<T = string | number> {
+  /**
+   * 当前选中值数组
+   */
+  value: T[];
+  /**
+   * 设置选中值数组
+   */
+  setValue: (value: T[]) => void;
+  /**
+   * 添加一个选中值
+   */
+  addValue: (value: T) => void;
+  /**
+   * 移除一个选中值
+   */
+  removeValue: (value: T) => void;
+  /**
+   * 清空所有选中值
+   */
+  clearValue: () => void;
+}
+/**
+ * 标签显示信息（多选专用）
+ * @template T 选项值的类型
+ */
+interface TagDisplayInfo<T = string | number> {
+  /**
+   * 可见的标签列表
+   */
+  visibleTags: SelectOption<T>[];
+  /**
+   * 隐藏的标签列表
+   */
+  hiddenTags: SelectOption<T>[];
+  /**
+   * 隐藏的标签数量
+   */
+  hiddenCount: number;
+}
+/**
+ * useSelectState Hook 的配置选项（单选）
+ * @template T 值的类型
+ */
+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 值的类型
+ */
+interface UseMultipleSelectStateOptions<T = string | number> {
+  /**
+   * 受控模式：当前值数组
+   */
+  value?: T[];
+  /**
+   * 非受控模式：默认值数组
+   */
+  defaultValue?: T[];
+  /**
+   * 值变化回调
+   */
+  onChange?: (value: T[], options: SelectOption<T>[]) => void;
+  /**
+   * 模式（用于类型区分）
+   */
+  mode: 'multiple';
+}
+/**
+ * 基础 Select Props（公共属性）
+ * @template T 值的类型
+ */
+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;
+}
+//#endregion
+export { BaseSelectProps, FilterOptionFunc, MultipleSelectState, SelectOption, SelectState, SortDirection, TagDisplayInfo, UseMultipleSelectStateOptions, UseSelectStateOptions };

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

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

package/lib/select/utils/filterOptions.js

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

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

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

package/lib/select/utils/helpers.js

@@ -0,0 +1,55 @@
+//#region src/select/utils/helpers.ts
+/**
+* 根据值查找选项对象
+* @template T 选项值的类型
+* @param value 选项值
+* @param options 选项列表
+* @returns 找到的选项对象，如果没找到返回 undefined
+*/
+function findOptionByValue(value, options) {
+	return options.find((opt) => opt.value === value);
+}
+/**
+* 根据值数组查找选项对象数组
+* @template T 选项值的类型
+* @param values 选项值数组
+* @param options 选项列表
+* @returns 找到的选项对象数组
+*/
+function findOptionsByValues(values, options) {
+	return values.map((val) => findOptionByValue(val, options)).filter(Boolean);
+}
+/**
+* 判断选项是否被选中（单选）
+* @template T 选项值的类型
+* @param optionValue 选项值
+* @param selectedValue 当前选中值
+* @returns 是否选中
+*/
+function isOptionSelected(optionValue, selectedValue) {
+	return selectedValue !== null && selectedValue !== void 0 && optionValue === selectedValue;
+}
+/**
+* 判断选项是否被选中（多选）
+* @template T 选项值的类型
+* @param optionValue 选项值
+* @param selectedValues 当前选中值数组
+* @returns 是否选中
+*/
+function isOptionSelectedInMultiple(optionValue, selectedValues) {
+	return selectedValues.includes(optionValue);
+}
+/**
+* 生成唯一 ID
+* @param prefix ID 前缀
+* @returns 唯一 ID
+*/
+function generateId(prefix = "select") {
+	return `${prefix}-${Math.random().toString(36).substr(2, 9)}`;
+}
+//#endregion
+exports.findOptionByValue = findOptionByValue;
+exports.findOptionsByValues = findOptionsByValues;
+exports.generateId = generateId;
+exports.isOptionSelected = isOptionSelected;
+exports.isOptionSelectedInMultiple = isOptionSelectedInMultiple;

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

@@ -0,0 +1,4 @@
+import { calculateTagDisplay } from "./tagAggregation.js";
+import { defaultFilterOption, filterOptions } from "./filterOptions.js";
+import { sortOptions } from "./sortOptions.js";
+import { findOptionByValue, findOptionsByValues, generateId, isOptionSelected, isOptionSelectedInMultiple } from "./helpers.js";

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

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

package/lib/select/utils/sortOptions.js

@@ -0,0 +1,20 @@
+//#region src/select/utils/sortOptions.ts
+/**
+* 排序选项列表
+* @template T 选项值的类型
+* @param options 原始选项列表
+* @param direction 排序方向（'asc' 升序 | 'desc' 降序）
+* @returns 排序后的选项列表（新数组）
+*/
+function sortOptions(options, direction = "asc") {
+	const sortedOptions = [...options];
+	sortedOptions.sort((a, b) => {
+		const labelA = a.label.toLowerCase();
+		const labelB = b.label.toLowerCase();
+		if (direction === "asc") return labelA.localeCompare(labelB);
+		else return labelB.localeCompare(labelA);
+	});
+	return sortedOptions;
+}
+//#endregion
+exports.sortOptions = sortOptions;

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

@@ -0,0 +1,25 @@
+import { SelectOption, TagDisplayInfo } from "../types.js";
+
+//#region src/select/utils/tagAggregation.d.ts
+/**
+ * 计算需要显示的标签和聚合信息
+ * @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
+ * // }
+ * ```
+ */
+declare function calculateTagDisplay<T = string | number>(selectedValues: T[], options: SelectOption<T>[], maxTagCount: number): TagDisplayInfo<T>;
+//#endregion
+export { calculateTagDisplay };

package/lib/select/utils/tagAggregation.js

@@ -0,0 +1,35 @@
+//#region src/select/utils/tagAggregation.ts
+/**
+* 计算需要显示的标签和聚合信息
+* @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
+* // }
+* ```
+*/
+function calculateTagDisplay(selectedValues, options, maxTagCount) {
+	const selectedOptions = selectedValues.map((v) => options.find((opt) => opt.value === v)).filter(Boolean);
+	if (selectedOptions.length <= maxTagCount) return {
+		visibleTags: selectedOptions,
+		hiddenTags: [],
+		hiddenCount: 0
+	};
+	return {
+		visibleTags: selectedOptions.slice(0, maxTagCount),
+		hiddenTags: selectedOptions.slice(maxTagCount),
+		hiddenCount: selectedOptions.length - maxTagCount
+	};
+}
+//#endregion
+exports.calculateTagDisplay = calculateTagDisplay;

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

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

package/lib/text-input/hooks/useTextInputState.js

@@ -0,0 +1,71 @@
+require("../../_virtual/_rolldown/runtime.js");
+const require_validation = require("../utils/validation.js");
+let react = require("react");
+//#region src/text-input/hooks/useTextInputState.ts
+/**
+* 文本输入状态管理 Hook
+* 
+* 管理组件的内部状态，包括：
+* - 值管理（受控/非受控模式）
+* - 校验状态管理
+* - 事件处理函数封装
+* 
+* 支持受控和非受控两种模式：
+* - 受控模式：value 由外部传入，组件不维护内部状态
+* - 非受控模式：使用 defaultValue，组件维护内部状态
+* 
+* @param props 组件 Props（包含校验配置）
+* @returns 文本输入状态对象
+* 
+* @example
+* // 受控模式
+* const state = useTextInputState({ value: 'hello', onChange: (v) => console.log(v) });
+* 
+* // 非受控模式
+* const state = useTextInputState({ defaultValue: 'hello' });
+*/
+function useTextInputState(props) {
+	const isControlled = props.value !== void 0;
+	const [innerValue, setInnerValue] = (0, react.useState)(props.defaultValue || "");
+	const [isTouched, setIsTouched] = (0, react.useState)(false);
+	const [isValid, setIsValid] = (0, react.useState)(true);
+	const [errors, setErrors] = (0, react.useState)([]);
+	const currentValue = isControlled ? props.value : innerValue;
+	return {
+		value: currentValue,
+		isTouched,
+		isValid,
+		errors,
+		handleChange: (0, react.useCallback)((newValue) => {
+			var _props$onChange;
+			if (!isControlled) setInnerValue(newValue);
+			if (props.validateTrigger === "onChange" || props.validateTrigger === "both") {
+				var _props$onValidate;
+				const validation = require_validation.validateValue(newValue, props);
+				setIsValid(validation.isValid);
+				setErrors(validation.errors);
+				(_props$onValidate = props.onValidate) === null || _props$onValidate === void 0 || _props$onValidate.call(props, validation.isValid, validation.errors);
+			}
+			(_props$onChange = props.onChange) === null || _props$onChange === void 0 || _props$onChange.call(props, newValue);
+		}, [isControlled, props]),
+		handleBlur: (0, react.useCallback)(() => {
+			var _props$onBlur;
+			setIsTouched(true);
+			if (props.validateTrigger !== "onChange") {
+				var _props$onValidate2;
+				const validation = require_validation.validateValue(currentValue || "", props);
+				setIsValid(validation.isValid);
+				setErrors(validation.errors);
+				(_props$onValidate2 = props.onValidate) === null || _props$onValidate2 === void 0 || _props$onValidate2.call(props, validation.isValid, validation.errors);
+			}
+			(_props$onBlur = props.onBlur) === null || _props$onBlur === void 0 || _props$onBlur.call(props, currentValue || "");
+		}, [currentValue, props]),
+		handleFocus: (0, react.useCallback)(() => {
+			var _props$onFocus;
+			setIsTouched(true);
+			(_props$onFocus = props.onFocus) === null || _props$onFocus === void 0 || _props$onFocus.call(props);
+		}, [props])
+	};
+}
+//#endregion
+exports.useTextInputState = useTextInputState;

package/lib/text-input/types.d.ts

@@ -0,0 +1,56 @@
+import { DisplayState, ValidationResult } from "../common/types.js";
+
+//#region src/text-input/types.d.ts
+/**
+ * 文本输入状态 Hook 返回值
+ */
+interface TextInputState {
+  /**
+   * 当前值
+   */
+  value: string | undefined;
+  /**
+   * 是否已被触摸（交互过）
+   */
+  isTouched: boolean;
+  /**
+   * 是否校验通过
+   */
+  isValid: boolean;
+  /**
+   * 错误信息数组
+   */
+  errors: string[];
+  /**
+   * 值变更处理函数
+   */
+  handleChange: (value: string) => void;
+  /**
+   * 失焦处理函数
+   */
+  handleBlur: () => void;
+  /**
+   * 聚焦处理函数
+   */
+  handleFocus: () => void;
+}
+/**
+ * 基础文本输入 Props（供校验和状态管理使用）
+ */
+interface BaseTextInputProps {
+  value?: string;
+  defaultValue?: string;
+  required?: boolean;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string | RegExp;
+  validator?: (value: string) => boolean | string;
+  validateTrigger?: 'onChange' | 'onBlur' | 'both';
+  errorMessage?: string;
+  onChange?: (value: string) => void;
+  onBlur?: (value: string) => void;
+  onFocus?: () => void;
+  onValidate?: (isValid: boolean, errors: string[]) => void;
+}
+//#endregion
+export { BaseTextInputProps, TextInputState };

package/lib/text-input/utils/validation.d.ts

@@ -0,0 +1,28 @@
+import { ValidationResult } from "../../common/types.js";
+import { BaseTextInputProps } from "../types.js";
+
+//#region src/text-input/utils/validation.d.ts
+/**
+ * 校验文本输入值
+ *
+ * 按照优先级执行校验规则：
+ * 1. 必填校验（required）
+ * 2. 最小长度校验（minLength）
+ * 3. 最大长度校验（maxLength）
+ * 4. 正则校验（pattern）
+ * 5. 自定义校验函数（validator）
+ *
+ * @param value 待校验的值
+ * @param props 校验配置
+ * @returns 校验结果对象，包含 isValid 和 errors
+ *
+ * @example
+ * validateValue('hello', { required: true, minLength: 3 })
+ * // { isValid: true, errors: [] }
+ *
+ * validateValue('', { required: true })
+ * // { isValid: false, errors: ['此字段为必填项'] }
+ */
+declare function validateValue(value: string, props: BaseTextInputProps): ValidationResult;
+//#endregion
+export { validateValue };