@pisell/materials 1.8.24 → 1.8.25

package/es/components/pisellLookup/types.d.ts

@@ -0,0 +1,667 @@
+import type React from 'react';
+/**
+ * 触发器类型
+ */
+export declare type TriggerType = 'input' | 'button' | 'icon' | 'text';
+/**
+ * 展示类型
+ */
+export declare type DisplayType = 'inline' | 'popup' | 'modal' | 'drawer' | 'detached';
+/**
+ * 搜索模式
+ */
+export declare type SearchMode = 'realtime' | 'confirm';
+/**
+ * 输入框尺寸
+ */
+export declare type SizeType = 'large' | 'middle' | 'small';
+/**
+ * PisellLookup Ref 接口
+ */
+export interface PisellLookupRef {
+    /**
+     * 打开搜索
+     */
+    open: () => void;
+    /**
+     * 关闭搜索
+     */
+    close: () => void;
+    /**
+     * 获取当前关键词
+     */
+    getKeyword: () => string;
+    /**
+     * 设置关键词
+     */
+    setKeyword: (keyword: string) => void;
+}
+/**
+ * Drawer 位置
+ */
+export declare type DrawerPlacement = 'left' | 'right' | 'top' | 'bottom';
+/**
+ * PisellLookup 组件 Props
+ */
+export interface PisellLookupProps {
+    /**
+     * 预设触发器类型（与 trigger 互斥）
+     * @default 'input'
+     */
+    triggerType?: TriggerType;
+    /**
+     * 自定义触发器（与 triggerType 互斥）
+     * 传入任意 ReactNode 作为触发器，点击时打开搜索
+     */
+    trigger?: React.ReactNode;
+    /**
+     * 触发器文本（triggerType='text' 时有效）
+     */
+    triggerText?: string;
+    /**
+     * 触发器图标（triggerType='icon' 时有效）
+     */
+    triggerIcon?: React.ReactNode;
+    /**
+     * 按钮文本（triggerType='button' 时有效）
+     * @default '搜索'
+     */
+    buttonText?: string;
+    /**
+     * 是否禁用
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 占位符文本
+     * @default '请输入搜索内容'
+     */
+    placeholder?: string;
+    /**
+     * 输入框尺寸
+     * @default 'default'
+     */
+    size?: SizeType;
+    /**
+     * 是否显示前缀图标
+     * @default false
+     */
+    showPrefixIcon?: boolean;
+    /**
+     * 前缀图标
+     */
+    prefixIcon?: React.ReactNode;
+    /**
+     * 是否显示清除按钮
+     * @default true
+     */
+    showClear?: boolean;
+    /**
+     * 是否显示确认触发按钮
+     * @default true
+     */
+    showConfirmButton?: boolean;
+    /**
+     * 确认按钮文本
+     * @default 'Lookup'
+     */
+    confirmButtonText?: string;
+    /**
+     * 搜索触发模式
+     * - realtime: 实时搜索（输入即触发）
+     * - confirm: 确认触发（点击按钮或按 Enter 键触发）
+     * 注意：如果 showConfirmButton=false，会自动使用 realtime 模式
+     * @default 'realtime'
+     */
+    searchMode?: SearchMode;
+    /**
+     * 防抖时间（毫秒）
+     * @default 300
+     */
+    debounceTime?: number;
+    /**
+     * 搜索关键词（受控）
+     */
+    value?: string;
+    /**
+     * 默认搜索关键词（非受控）
+     */
+    defaultValue?: string;
+    /**
+     * 关键词变化回调
+     * @param value 当前关键词
+     */
+    onChange?: (value: string) => void;
+    /**
+     * 搜索触发回调
+     * @param keyword 搜索关键词
+     */
+    onSearch?: (keyword: string) => void;
+    /**
+     * 是否显示扫码按钮
+     * @default true
+     */
+    showScan?: boolean;
+    /**
+     * 扫码完成回调
+     * @param code 扫码结果
+     */
+    onScan?: (code: string) => void;
+    /**
+     * 是否显示搜索历史
+     * @default false
+     */
+    showHistory?: boolean;
+    /**
+     * 历史记录存储 key
+     * @default 'pisell_lookup_history'
+     */
+    historyKey?: string;
+    /**
+     * 历史记录数量上限
+     * @default 10
+     */
+    maxHistoryCount?: number;
+    /**
+     * 加载历史记录回调（用于自定义存储）
+     * @returns 历史记录数组
+     */
+    onLoadHistory?: () => string[];
+    /**
+     * 保存历史记录回调（用于自定义存储）
+     * @param history 历史记录数组
+     */
+    onSaveHistory?: (history: string[]) => void;
+    /**
+     * 自定义历史记录渲染
+     * @param history 历史记录数组
+     * @param onSelect 选择历史记录的回调
+     * @returns 渲染内容
+     */
+    historyRender?: (history: string[], onSelect: (keyword: string) => void) => React.ReactNode;
+    /**
+     * 是否显示联想词
+     * @default false
+     */
+    showSuggestions?: boolean;
+    /**
+     * 加载联想词回调
+     * @param keyword 当前输入的关键词
+     * @returns 联想词数组或 Promise
+     */
+    onLoadSuggestions?: (keyword: string) => Promise<string[]> | string[];
+    /**
+     * 自定义联想词渲染
+     * @param suggestions 联想词数组
+     * @param onSelect 选择联想词的回调
+     * @returns 渲染内容
+     */
+    suggestionsRender?: (suggestions: string[], onSelect: (keyword: string) => void) => React.ReactNode;
+    /**
+     * 是否显示热门搜索
+     * @default false
+     */
+    showHotWords?: boolean;
+    /**
+     * 加载热门搜索回调
+     * @returns 热门搜索数组或 Promise
+     */
+    onLoadHotWords?: () => Promise<string[]> | string[];
+    /**
+     * 自定义热门搜索渲染
+     * @param hotWords 热门搜索数组
+     * @param onSelect 选择热门搜索的回调
+     * @returns 渲染内容
+     */
+    hotWordsRender?: (hotWords: string[], onSelect: (keyword: string) => void) => React.ReactNode;
+    /**
+     * 结果展示方式
+     * 如果不指定，将根据 triggerType 智能判断：
+     * - triggerType='input' → 'inline'
+     * - 其他 → 'modal'
+     */
+    displayType?: DisplayType;
+    /**
+     * 结果渲染函数
+     * @param keyword 搜索关键词
+     * @param onClose 关闭搜索的回调（可选）
+     * @returns 渲染的结果内容
+     */
+    resultRender?: (keyword: string, onClose?: () => void) => React.ReactNode;
+    /**
+     * 是否显示加载状态
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * 空状态渲染
+     * @returns 空状态内容
+     */
+    emptyRender?: () => React.ReactNode;
+    /**
+     * Modal 宽度
+     * @default 834
+     */
+    modalWidth?: number | string;
+    /**
+     * Modal 自定义样式
+     */
+    modalStyle?: React.CSSProperties;
+    /**
+     * Modal 挂载节点
+     * - HTMLElement: 挂载到指定的 DOM 节点
+     * - () => HTMLElement: 返回挂载节点的函数
+     * - false: 挂载到触发器的父节点
+     * - undefined: 默认挂载到 document.body
+     * @default undefined
+     */
+    getContainer?: HTMLElement | (() => HTMLElement) | false;
+    /**
+     * Drawer 宽度
+     * @default 378
+     */
+    drawerWidth?: number | string;
+    /**
+     * Drawer 位置
+     * @default 'right'
+     */
+    drawerPlacement?: DrawerPlacement;
+    /**
+     * Popup 宽度
+     */
+    popupWidth?: number | string;
+    /**
+     * 容器自定义样式
+     */
+    containerStyle?: React.CSSProperties;
+    /**
+     * 容器自定义类名
+     */
+    containerClassName?: string;
+    /**
+     * 是否可见（受控）
+     */
+    visible?: boolean;
+    /**
+     * 默认是否可见（非受控）
+     * @default false
+     */
+    defaultVisible?: boolean;
+    /**
+     * 可见性变化回调
+     * @param visible 当前可见性
+     */
+    onVisibleChange?: (visible: boolean) => void;
+    /**
+     * 打开回调
+     */
+    onOpen?: () => void;
+    /**
+     * 关闭回调
+     */
+    onClose?: () => void;
+    /**
+     * 是否显示遮罩层（仅 Modal/Drawer）
+     * @default false
+     */
+    mask?: boolean;
+    /**
+     * 点击遮罩是否关闭（仅 Modal/Drawer）
+     * 注意：只有 mask=true 时此配置才生效
+     * @default true
+     */
+    maskClosable?: boolean;
+    /**
+     * 关闭时是否清空关键词
+     * @default false
+     */
+    clearOnClose?: boolean;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: React.CSSProperties;
+    /**
+     * 层级
+     */
+    zIndex?: number;
+}
+/**
+ * LookupTrigger Ref 接口
+ */
+export interface LookupTriggerRef {
+    /**
+     * 聚焦到输入框
+     */
+    focus: () => void;
+    /**
+     * 选中输入框文字
+     */
+    select: () => void;
+}
+/**
+ * LookupTrigger 组件 Props
+ */
+export interface LookupTriggerProps {
+    /**
+     * 触发器类型
+     */
+    type?: TriggerType;
+    /**
+     * 自定义触发器
+     */
+    trigger?: React.ReactNode;
+    /**
+     * 触发器文本
+     */
+    triggerText?: string;
+    /**
+     * 触发器图标
+     */
+    triggerIcon?: React.ReactNode;
+    /**
+     * 按钮文本
+     */
+    buttonText?: string;
+    /**
+     * 是否禁用
+     */
+    disabled?: boolean;
+    /**
+     * 占位符
+     */
+    placeholder?: string;
+    /**
+     * 尺寸
+     */
+    size?: SizeType;
+    /**
+     * 是否显示前缀图标
+     */
+    showPrefixIcon?: boolean;
+    /**
+     * 前缀图标
+     */
+    prefixIcon?: React.ReactNode;
+    /**
+     * 是否显示清除按钮
+     */
+    showClear?: boolean;
+    /**
+     * 是否显示确认按钮
+     */
+    showConfirmButton?: boolean;
+    /**
+     * 确认按钮文本
+     */
+    confirmButtonText?: string;
+    /**
+     * 是否显示扫码按钮
+     */
+    showScan?: boolean;
+    /**
+     * 当前值
+     */
+    value?: string;
+    /**
+     * 值变化回调
+     */
+    onChange?: (value: string) => void;
+    /**
+     * 点击事件
+     */
+    onClick?: () => void;
+    /**
+     * 聚焦事件
+     */
+    onFocus?: () => void;
+    /**
+     * 确认触发回调
+     */
+    /** 确认搜索（回车或点击按钮）；可传入当前输入值，受控下回车时传 input 当前值以保证历史能正确保存 */
+    onConfirm?: (value?: string) => void;
+    /**
+     * 扫码回调
+     */
+    onScan?: (code: string) => void;
+    /**
+     * 清除回调
+     */
+    onClear?: () => void;
+    /**
+     * 失焦回调
+     */
+    onBlur?: () => void;
+    /**
+     * 是否自动聚焦
+     */
+    autoFocus?: boolean;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: React.CSSProperties;
+}
+/**
+ * LookupAuxiliary 组件 Props
+ */
+export interface LookupAuxiliaryProps {
+    /**
+     * 当前关键词
+     */
+    keyword: string;
+    /**
+     * 是否显示搜索历史
+     */
+    showHistory?: boolean;
+    /**
+     * 搜索历史数组
+     */
+    history?: string[];
+    /**
+     * 是否显示联想词
+     */
+    showSuggestions?: boolean;
+    /**
+     * 联想词数组
+     */
+    suggestions?: string[];
+    /**
+     * 是否显示热门搜索
+     */
+    showHotWords?: boolean;
+    /**
+     * 热门搜索数组
+     */
+    hotWords?: string[];
+    /**
+     * 选择回调
+     */
+    onSelect?: (keyword: string) => void;
+    /**
+     * 删除历史记录回调
+     */
+    onRemoveHistory?: (keyword: string) => void;
+    /**
+     * 清除全部历史记录回调
+     */
+    onClearHistory?: () => void;
+    /**
+     * 自定义历史记录渲染
+     */
+    historyRender?: (history: string[], onSelect: (keyword: string) => void) => React.ReactNode;
+    /**
+     * 自定义联想词渲染
+     */
+    suggestionsRender?: (suggestions: string[], onSelect: (keyword: string) => void) => React.ReactNode;
+    /**
+     * 自定义热门搜索渲染
+     */
+    hotWordsRender?: (hotWords: string[], onSelect: (keyword: string) => void) => React.ReactNode;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: React.CSSProperties;
+}
+/**
+ * LookupResultHost 组件 Props
+ */
+export interface LookupResultHostProps {
+    /**
+     * 展示类型
+     */
+    displayType: DisplayType;
+    /**
+     * 是否可见
+     */
+    visible: boolean;
+    /**
+     * 关闭回调
+     */
+    onClose: () => void;
+    /**
+     * 子元素（输入区 + 辅助区 + 结果区）
+     */
+    children: React.ReactNode;
+    /**
+     * Modal 宽度
+     */
+    modalWidth?: number | string;
+    /**
+     * Modal 样式
+     */
+    modalStyle?: React.CSSProperties;
+    /**
+     * Modal 挂载节点
+     */
+    getContainer?: HTMLElement | (() => HTMLElement) | false;
+    /**
+     * Drawer 宽度
+     */
+    drawerWidth?: number | string;
+    /**
+     * Drawer 位置
+     */
+    drawerPlacement?: DrawerPlacement;
+    /**
+     * Popup 宽度
+     */
+    popupWidth?: number | string;
+    /**
+     * 容器样式
+     */
+    containerStyle?: React.CSSProperties;
+    /**
+     * 容器类名
+     */
+    containerClassName?: string;
+    /**
+     * 是否显示遮罩层
+     */
+    mask?: boolean;
+    /**
+     * 点击遮罩是否关闭
+     */
+    maskClosable?: boolean;
+    /**
+     * 层级
+     */
+    zIndex?: number;
+    /**
+     * Modal/Drawer 打开后的回调
+     */
+    onAfterOpen?: () => void;
+}
+/**
+ * SearchHistory 组件 Props
+ */
+export interface SearchHistoryProps {
+    /**
+     * 历史记录数组
+     */
+    history: string[];
+    /**
+     * 选择历史记录回调
+     */
+    onSelect: (keyword: string) => void;
+    /**
+     * 删除历史记录回调
+     */
+    onRemove?: (keyword: string) => void;
+    /**
+     * 清除全部历史记录回调
+     */
+    onClear?: () => void;
+    /**
+     * 自定义渲染
+     */
+    render?: (history: string[], onSelect: (keyword: string) => void) => React.ReactNode;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: React.CSSProperties;
+}
+/**
+ * SuggestWords 组件 Props
+ */
+export interface SuggestWordsProps {
+    /**
+     * 联想词数组
+     */
+    suggestions: string[];
+    /**
+     * 选择联想词回调
+     */
+    onSelect: (keyword: string) => void;
+    /**
+     * 自定义渲染
+     */
+    render?: (suggestions: string[], onSelect: (keyword: string) => void) => React.ReactNode;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: React.CSSProperties;
+}
+/**
+ * HotWords 组件 Props
+ */
+export interface HotWordsProps {
+    /**
+     * 热门搜索数组
+     */
+    hotWords: string[];
+    /**
+     * 选择热门搜索回调
+     */
+    onSelect: (keyword: string) => void;
+    /**
+     * 自定义渲染
+     */
+    render?: (hotWords: string[], onSelect: (keyword: string) => void) => React.ReactNode;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: React.CSSProperties;
+}

package/es/components/pisellLookup/utils/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 工具函数统一导出
+ */
+export * from './storage';
+export * from './trigger';

package/es/components/pisellLookup/utils/storage.d.ts

@@ -0,0 +1,42 @@
+/**
+ * localStorage 工具函数
+ * 用于管理搜索历史的存储
+ */
+/**
+ * 从 localStorage 加载历史记录
+ * @param key 存储的 key
+ * @returns 历史记录数组
+ */
+export declare const loadHistory: (key: string) => string[];
+/**
+ * 保存历史记录到 localStorage
+ * @param key 存储的 key
+ * @param history 历史记录数组
+ * @param maxCount 最大数量限制
+ */
+export declare const saveHistory: (key: string, history: string[], maxCount: number) => void;
+/**
+ * 清除历史记录
+ * @param key 存储的 key
+ */
+export declare const clearHistory: (key: string) => void;
+/**
+ * 添加历史记录项
+ * @param key 存储的 key
+ * @param item 新的历史记录项
+ * @param maxCount 最大数量限制
+ * @returns 更新后的历史记录数组
+ */
+export declare const addHistoryItem: (key: string, item: string, maxCount: number) => string[];
+/**
+ * 删除历史记录项
+ * @param key 存储的 key
+ * @param item 要删除的历史记录项
+ * @returns 更新后的历史记录数组
+ */
+export declare const removeHistoryItem: (key: string, item: string) => string[];
+/**
+ * 检查 localStorage 是否可用
+ * @returns 是否可用
+ */
+export declare const isLocalStorageAvailable: () => boolean;