@pisell/materials 6.11.224 → 6.12.1

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

@@ -0,0 +1,761 @@
+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 LookupSearchSource = 'keyboard' | 'scan';
+/**
+ * 输入框尺寸
+ */
+export declare type SizeType = 'large' | 'middle' | 'small';
+/**
+ * PisellLookup Ref 接口
+ */
+export interface PisellLookupRef {
+    /**
+     * 打开搜索
+     */
+    open: () => void;
+    /**
+     * 关闭搜索
+     */
+    close: () => void;
+    /**
+     * 获取当前关键词
+     */
+    getKeyword: () => string;
+    /**
+     * 设置关键词
+     */
+    setKeyword: (keyword: string, source?: LookupSearchSource) => void;
+}
+/**
+ * Drawer 位置
+ */
+export declare type DrawerPlacement = 'left' | 'right' | 'top' | 'bottom';
+/**
+ * 输入栏插槽上下文
+ *
+ * 通过 `inputRender` 自定义「输入框」形态触发器时，组件会把内部已经接好的受控状态与回调
+ * 透传给插槽。插槽只需把这些值绑定到自定义输入控件上，即可完全复用 PisellLookup 的
+ * 搜索状态机（受控值 / 防抖实时搜索 / 确认搜索 / 历史 / inline·popup 聚焦展开等）。
+ *
+ * 仅在 `triggerType='input'`（或 modal/drawer 内置输入框）形态下生效；button/icon/text
+ * 触发器不会调用 `inputRender`。
+ */
+export interface LookupInputRenderContext {
+    /** 当前关键词（受控值） */
+    value: string;
+    /** 占位符 */
+    placeholder?: string;
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** 尺寸 */
+    size?: SizeType;
+    /** 是否处于加载态（透传自 PisellLookup 的 loading） */
+    loading?: boolean;
+    /** 输入变化：写回关键词（受控） */
+    onChange: (value: string) => void;
+    /** 确认搜索：回车 / 点击搜索按钮时调用，可显式传入当前值 */
+    onConfirm: (value?: string) => void;
+    /** 清除：清空关键词并恢复结果 */
+    onClear: () => void;
+    /** 扫码结果回填 */
+    onScan?: (code: string) => void;
+    /** 最近一次搜索来源，用于输入栏区分键盘输入与扫码结果态 */
+    searchSource?: LookupSearchSource;
+    /** 聚焦：inline/popup 形态用于展开结果容器 */
+    onFocus?: () => void;
+    /** 失焦：inline/popup 形态用于延迟关闭结果容器 */
+    onBlur?: () => void;
+}
+/**
+ * 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;
+    /**
+     * 输入框前置内容（透传给底层 antd Input 的 `addonBefore`）。
+     *
+     * 与输入框连成一体显示在左侧，例如在搜索框内嵌一个「搜索字段」Select。
+     * 仅 `triggerType='input'` 形态生效。
+     */
+    addonBefore?: React.ReactNode;
+    /**
+     * 是否显示清除按钮
+     * @default true
+     */
+    showClear?: boolean;
+    /**
+     * 是否显示确认触发按钮
+     * @default true
+     */
+    showConfirmButton?: boolean;
+    /**
+     * 确认按钮文本
+     * @default 'Lookup'
+     */
+    confirmButtonText?: string;
+    /**
+     * Modal 搜索栏关闭按钮文本
+     * @default 'Close'
+     */
+    closeButtonText?: 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;
+    /**
+     * Modal/Drawer 打开后是否自动聚焦输入框
+     * @default true
+     */
+    autoFocusOnOpen?: boolean;
+    /**
+     * 输入栏插槽
+     *
+     * 自定义「输入框」形态的触发器渲染。传入后会**替换内置 antd Input**，但完整复用
+     * PisellLookup 的搜索状态机（受控值 / 实时·确认搜索 / 历史 / 容器形态）。
+     * 仅 input 形态生效（含 modal/drawer 内置输入框），button/icon/text 触发器不受影响。
+     *
+     * @example
+     * ```tsx
+     * <PisellLookup
+     *   inputRender={(ctx) => (
+     *     <MyInput
+     *       value={ctx.value}
+     *       onChange={ctx.onChange}
+     *       onSearch={ctx.onConfirm}
+     *     />
+     *   )}
+     * />
+     * ```
+     */
+    inputRender?: (ctx: LookupInputRenderContext) => React.ReactNode;
+    /**
+     * 自定义类名
+     */
+    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;
+    /**
+     * 输入框前置内容（透传给底层 antd Input 的 `addonBefore`）
+     */
+    addonBefore?: React.ReactNode;
+    /**
+     * 是否显示清除按钮
+     */
+    showClear?: boolean;
+    /**
+     * 是否显示确认按钮
+     */
+    showConfirmButton?: boolean;
+    /**
+     * 确认按钮文本
+     */
+    confirmButtonText?: string;
+    /**
+     * 是否显示扫码按钮
+     */
+    showScan?: boolean;
+    /**
+     * 当前值
+     */
+    value?: string;
+    /**
+     * 最近一次搜索来源
+     */
+    searchSource?: LookupSearchSource;
+    /**
+     * 值变化回调
+     */
+    onChange?: (value: string) => void;
+    /**
+     * 点击事件
+     */
+    onClick?: () => void;
+    /**
+     * 聚焦事件
+     */
+    onFocus?: () => void;
+    /**
+     * 确认触发回调
+     */
+    /** 确认搜索（回车或点击按钮）；可传入当前输入值，受控下回车时传 input 当前值以保证历史能正确保存 */
+    onConfirm?: (value?: string) => void;
+    /**
+     * 扫码回调
+     */
+    onScan?: (code: string) => void;
+    /**
+     * 清除回调
+     */
+    onClear?: () => void;
+    /**
+     * 失焦回调
+     */
+    onBlur?: () => void;
+    /**
+     * 是否自动聚焦
+     */
+    autoFocus?: boolean;
+    /**
+     * 加载态（透传给输入栏插槽 ctx.loading）
+     */
+    loading?: boolean;
+    /**
+     * 输入栏插槽：自定义 input 形态触发器渲染（仅 type='input' 生效）
+     */
+    inputRender?: (ctx: LookupInputRenderContext) => React.ReactNode;
+    /**
+     * 自定义类名
+     */
+    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;
+}