@rainbow-oh/yee-c 0.14.7 → 0.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainbow-oh/yee-c",
-  "version": "0.14.7",
+  "version": "0.15.1",
   "description": "yee basic components",
   "keywords": [
     "react",

package/src/Form/index.ts

@@ -29,9 +29,13 @@ Form.List = List;
 
 export type {
   FieldGroupProps,
+  FieldProps,
   FieldStatus,
   FieldStatusData,
+  FieldTooltip,
   FormInstance,
+  FormListField,
+  FormListOperation,
   FormListProps,
   FormProps,
   Rule as FormRule,

package/src/Input/style/index.less

@@ -45,6 +45,7 @@
     box-shadow: none;
     height: auto;
     padding: 0;
+    border-radius: 0;
   }
 
   &-inner {

package/src/InputNumber/demo/basic.tsx

@@ -8,7 +8,7 @@ import React from 'react';
 export default () => {
   return (
     <InputNumber
-      defaultValue={0}
+      defaultValue={123}
       placeholder="Enter a number"
       onChange={(value) => console.log('value:', value)}
     />

package/src/InputNumber/index.en-US.md

@@ -63,8 +63,8 @@ Enter a number within certain range with the mouse or keyboard.
 | Property | Type | Description | Default |
 | --- | --- | --- | --- |
 | prefixCls | `string` | Custom class name prefix | - |
-| value | `number \| null` | Current value | - |
-| defaultValue | `number \| null` | Default value | - |
+| value | `number \| string \| null` | Current value (`''` is treated as empty and never renders as 0 with a formatter) | - |
+| defaultValue | `number \| string \| null` | Default value | - |
 | min | `number` | Minimum value | -Infinity |
 | max | `number` | Maximum value | Infinity |
 | step | `number` | Step value | `1` |

package/src/InputNumber/index.zh-CN.md

@@ -67,8 +67,8 @@ toc: 'content'
 | 属性名 | 类型 | 描述 | 默认值 |
 | --- | --- | --- | --- |
 | prefixCls | `string` | 自定义类名前缀 | - |
-| value | `number \| null` | 受控的值 | - |
-| defaultValue | `number \| null` | 默认值 | - |
+| value | `number \| string \| null` | 受控的值（`''` 视为空值，配 formatter 也不会渲染成 0） | - |
+| defaultValue | `number \| string \| null` | 默认值 | - |
 | min | `number` | 最小值 | -Infinity |
 | max | `number` | 最大值 | Infinity |
 | step | `number` | 步长 | `1` |

package/src/InputNumber/input-number.tsx

@@ -49,7 +49,7 @@ const InputNumber = forwardRef<HTMLInputElement, InputNumberProps>(
       ...rest
     } = props;
 
-    const [mergedValue, setMergedValue] = useMergedState<number | null>(null, {
+    const [mergedValue, setMergedValue] = useMergedState<number | string | null>(null, {
       value,
       defaultValue,
     });
@@ -57,9 +57,24 @@ const InputNumber = forwardRef<HTMLInputElement, InputNumberProps>(
     const [focused, setFocused] = useState(false);
     const inputRef = useRef<HTMLInputElement>(null);
 
+    /** 字符串值（表单 store 常见）参与算术/比较前转数字；不可解析返回 null */
+    function toNumber(val: number | string | null | undefined): number | null {
+      if (val === null || val === undefined || val === '') return null;
+      const n = Number(val);
+      return Number.isNaN(n) ? null : n;
+    }
+
     // Format value
-    function formatValue(val: number | null | undefined): string {
-      if (val === null || val === undefined || isNaN(val)) return '';
+    function formatValue(val: number | string | null | undefined): string {
+      // '' 与 null/undefined 同为空值：Number('') === 0，若不拦截会被
+      // formatter/precision 格式化成 '0'（如全局千分位 formatter 场景）
+      if (
+        val === null ||
+        val === undefined ||
+        val === '' ||
+        isNaN(val as number)
+      )
+        return '';
 
       let formattedVal =
         precision !== undefined ? Number(val).toFixed(precision) : val;
@@ -149,7 +164,7 @@ const InputNumber = forwardRef<HTMLInputElement, InputNumberProps>(
       if (disabled || readOnly) return;
 
       const offset = type === 'up' ? step : -step;
-      const currentValue = mergedValue ?? 0;
+      const currentValue = toNumber(mergedValue) ?? 0;
       const newValue = currentValue + offset;
 
       updateValue(newValue);
@@ -259,7 +274,10 @@ const InputNumber = forwardRef<HTMLInputElement, InputNumberProps>(
                     {
                       [`${prefixCls}-handler-disabled`]:
                         disabled ||
-                        (mergedValue !== null && mergedValue >= max),
+                        (() => {
+                          const n = toNumber(mergedValue);
+                          return n !== null && n >= max;
+                        })(),
                     },
                   )}
                   onClick={() => handleStep('up')}
@@ -273,7 +291,10 @@ const InputNumber = forwardRef<HTMLInputElement, InputNumberProps>(
                     {
                       [`${prefixCls}-handler-disabled`]:
                         disabled ||
-                        (mergedValue !== null && mergedValue <= min),
+                        (() => {
+                          const n = toNumber(mergedValue);
+                          return n !== null && n <= min;
+                        })(),
                     },
                   )}
                   onClick={() => handleStep('down')}

package/src/InputNumber/interface.ts

@@ -34,13 +34,13 @@ export interface InputNumberProps extends Omit<
    */
   size?: 'small' | 'default' | 'large';
   /**
-   * Controlled value
+   * Controlled value（'' 视为空值，配合 formatter 不会渲染成 0）
    */
-  value?: number | null;
+  value?: number | string | null;
   /**
    * Default value
    */
-  defaultValue?: number | null;
+  defaultValue?: number | string | null;
   /**
    * Minimum value
    */

package/src/InputNumber/style/index.less

@@ -13,6 +13,7 @@
   border-radius: var(--yee-input-border-radius, 4px);
   background-color: var(--yee-input-content-bg-color);
   transition: all 0.3s;
+  overflow: hidden;
 
   &:not(@{pls}-disabled):hover {
     border-color: var(--yee-input-hover-border-color);

package/src/Select/hooks/useSelectKeyboard.ts

@@ -261,8 +261,13 @@ export default function useSelectKeyboard({
         handleEnter();
         break;
       case 'Escape':
-        event.preventDefault();
-        handleEscape();
+        // Only swallow Escape while open so outer layers (e.g. a Dialog's
+        // useEsc listening on document) still receive it when closed.
+        if (open) {
+          event.preventDefault();
+          event.stopPropagation();
+          handleEscape();
+        }
         break;
       default:
     }

package/src/Selector/selector.tsx

@@ -284,12 +284,17 @@ const Selector = React.forwardRef(
         aria-disabled={disabled || undefined}
         onKeyDown={(event) => {
           if (disabled) return;
-          // For non-searchable single select, handle Enter to open dropdown
-          if (!searchable && event.key === 'Enter' && !open) {
-            onOpenChange?.(true);
+          // Enter opens the dropdown while it is closed
+          if (event.key === 'Enter' && !open && onOpenChange) {
+            event.preventDefault();
+            onOpenChange(true);
+          }
+          // Input forwards this handler for its own keydowns; handling them
+          // here too would fire the handler twice per keypress. Only handle
+          // events that originate on the container (non-searchable focus).
+          if (event.target !== inputRef.current) {
+            externalOnKeyDown?.(event as React.KeyboardEvent<HTMLInputElement>);
           }
-          // Also call external onKeyDown if provided
-          externalOnKeyDown?.(event as React.KeyboardEvent<HTMLInputElement>);
         }}
         ref={ref}
       >

package/src/TableSelect/hooks/useTableSelectKeyboard.ts

@@ -0,0 +1,141 @@
+import { useEffect, useRef, useState } from 'react';
+import type { TableSelectDataType } from '../interface';
+
+type KeyType = string | number;
+
+interface UseTableSelectKeyboardParams {
+  open: boolean;
+  disabled?: boolean;
+  dataSource: Array<TableSelectDataType>;
+  rowKey: string | ((record: any) => string);
+  selectionType: 'radio' | 'checkbox';
+  selectedRowKeys: Array<KeyType>;
+  searchValue: string;
+  onSelect: (keys: Array<KeyType>, rows: Array<TableSelectDataType>) => void;
+  onClose: () => void;
+}
+
+/**
+ * Keyboard navigation for the popup table. The highlight is positional (like a
+ * hover cursor): `activeRow` is a rendered row index, and Space selects the
+ * record displayed there. The rendered order is the filter→sort→paginate
+ * result inside Table and is not derivable from `dataSource`, so the row count
+ * and the highlighted row's key are both read from the popup DOM.
+ */
+export default function useTableSelectKeyboard({
+  open,
+  disabled,
+  dataSource,
+  rowKey,
+  selectionType,
+  selectedRowKeys,
+  searchValue,
+  onSelect,
+  onClose,
+}: UseTableSelectKeyboardParams) {
+  const popupRef = useRef<HTMLDivElement | null>(null);
+  // 1-based index of the highlighted row (`tr[data-row-index]`), 0 = none.
+  const [activeRow, setActiveRow] = useState(0);
+
+  useEffect(() => {
+    setActiveRow(0);
+  }, [open, searchValue]);
+
+  const getRecordKey = (item: TableSelectDataType) =>
+    typeof rowKey === 'function' ? rowKey(item) : item[rowKey];
+
+  const getRowCount = () =>
+    popupRef.current?.querySelectorAll('tr[data-row-index]').length ?? 0;
+
+  useEffect(() => {
+    if (!open || activeRow < 1) return;
+    const rowEl = popupRef.current?.querySelector(
+      `tr[data-row-index="${activeRow}"]`,
+    ) as HTMLElement | null;
+    if (!rowEl) return;
+    // Manual scroll instead of scrollIntoView: the popup renders in a portal,
+    // and scrollIntoView would scroll the page as well as the popup.
+    let parent = rowEl.parentElement;
+    while (parent && parent !== popupRef.current) {
+      const { overflowY } = window.getComputedStyle(parent);
+      if (
+        /(auto|scroll)/.test(overflowY) &&
+        parent.scrollHeight > parent.clientHeight
+      ) {
+        const parentRect = parent.getBoundingClientRect();
+        const rowRect = rowEl.getBoundingClientRect();
+        if (rowRect.bottom > parentRect.bottom) {
+          parent.scrollTop += rowRect.bottom - parentRect.bottom;
+        } else if (rowRect.top < parentRect.top) {
+          parent.scrollTop -= parentRect.top - rowRect.top;
+        }
+        return;
+      }
+      parent = parent.parentElement;
+    }
+  }, [activeRow, open]);
+
+  const selectActiveRow = () => {
+    const rowEl = popupRef.current?.querySelector(
+      `tr[data-row-index="${activeRow}"]`,
+    );
+    const inputEl = rowEl?.querySelector(
+      'input[type="radio"],input[type="checkbox"]',
+    ) as HTMLInputElement | null;
+    if (!inputEl || inputEl.disabled) return;
+
+    const record = dataSource.find(
+      (item) => String(getRecordKey(item)) === inputEl.value,
+    );
+    if (!record) return;
+    const key = getRecordKey(record);
+
+    if (selectionType === 'radio') {
+      // Same shape as the click path: arrays, normalized by the consumer.
+      onSelect([key], [record]);
+      onClose();
+      return;
+    }
+
+    const checked = selectedRowKeys.some((k) => String(k) === String(key));
+    const nextKeys = checked
+      ? selectedRowKeys.filter((k) => String(k) !== String(key))
+      : [...selectedRowKeys, key];
+    const rows = dataSource.filter((item) =>
+      nextKeys.some((k) => String(getRecordKey(item)) === String(k)),
+    );
+    onSelect(nextKeys, rows);
+  };
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
+    if (!open || disabled) return;
+    switch (event.key) {
+      case 'ArrowDown':
+        event.preventDefault();
+        setActiveRow(Math.min(activeRow + 1, getRowCount()));
+        break;
+      case 'ArrowUp':
+        event.preventDefault();
+        setActiveRow(activeRow <= 1 ? getRowCount() : activeRow - 1);
+        break;
+      case ' ':
+        // With nothing highlighted, space keeps its native input behavior.
+        if (activeRow > 0) {
+          event.preventDefault();
+          selectActiveRow();
+        }
+        break;
+      case 'Escape':
+        event.preventDefault();
+        // Stop the event from reaching outer layers (e.g. a Dialog's useEsc
+        // listening on document) so only the dropdown closes.
+        event.stopPropagation();
+        onClose();
+        break;
+      default:
+        break;
+    }
+  };
+
+  return { popupRef, activeRow, handleKeyDown };
+}

package/src/TableSelect/index.en-US.md

@@ -31,45 +31,45 @@ A component for selecting one or more options from table data, combining feature
 
 ### TableSelectProps
 
-| Property | Type | Description | Default Value |
-| --- | --- | --- | --- |
-| prefixCls | `string` | Custom class name prefix | `'yee-table-select'` |
-| className | `string` | Root element class name | - |
-| style | `React.CSSProperties` | Root element inline styles | - |
-| rowKey | `string \| ((record: any) => string)` | Unique identifier field name for data | `'id'` |
-| columns | `Array<any>` | Table column configuration | - |
-| dataSource | `Array<InDataType>` | Data source | - |
-| rowSelection | `RowSelectionType` | Row selection configuration | - |
-| value | `SelectionKeyType \| SelectionKeyType[]` | Controlled value | - |
-| defaultValue | `SelectionKeyType \| SelectionKeyType[]` | Default value | - |
-| disabled | `boolean` | Whether disabled | - |
-| loading | `boolean` | Whether data is loading; displays a gray loading indicator | `false` |
-| placement | `'bottomLeft' \| 'topLeft'` | Popup placement | `'bottomLeft'` |
-| searchable | `boolean` | Whether searchable | `true` |
-| searchOnInput | `boolean` | Whether to search while typing | `true` |
-| allowClear | `boolean` | Whether allow clear | `true` |
-| closable | `boolean` | Whether tags are closable | `true` |
-| placeholder | `string` | Placeholder text | - |
-| optionLabelProp | `string \| ((option: InDataType) => string)` | Option label property | `'name'` |
-| type | `'radio' \| 'checkbox'` | Selection type | `'radio'` |
-| options | `TagType[]` | Preset options | - |
-| isShowFilter | `boolean` | Whether to show filter (All/Selected for multiple) | `true` |
-| containerId | `string` | Container ID (for popup mounting) | - |
-| io | `'out'` | Input direction | - |
-| onChange | `(keys, data, checked, changeData) => void` | Selection change callback | - |
-| onSearch | `(value: string, e?) => void` | Search callback | - |
-| onOpenChange | `(open: boolean) => void` | Popup state change callback | - |
+| Property        | Type                                                  | Description                                                | Default Value        |
+| --------------- | ----------------------------------------------------- | ---------------------------------------------------------- | -------------------- |
+| prefixCls       | `string`                                              | Custom class name prefix                                   | `'yee-table-select'` |
+| className       | `string`                                              | Root element class name                                    | -                    |
+| style           | `React.CSSProperties`                                 | Root element inline styles                                 | -                    |
+| rowKey          | `string \| ((record: any) => string)`                 | Unique identifier field name for data                      | `'id'`               |
+| columns         | `Array<any>`                                          | Table column configuration                                 | -                    |
+| dataSource      | `Array<TableSelectDataType>`                          | Data source                                                | -                    |
+| rowSelection    | `RowSelectionType`                                    | Row selection configuration                                | -                    |
+| value           | `SelectionKeyType \| SelectionKeyType[]`              | Controlled value                                           | -                    |
+| defaultValue    | `SelectionKeyType \| SelectionKeyType[]`              | Default value                                              | -                    |
+| disabled        | `boolean`                                             | Whether disabled                                           | -                    |
+| loading         | `boolean`                                             | Whether data is loading; displays a gray loading indicator | `false`              |
+| placement       | `'bottomLeft' \| 'topLeft'`                           | Popup placement                                            | `'bottomLeft'`       |
+| searchable      | `boolean`                                             | Whether searchable                                         | `true`               |
+| searchOnInput   | `boolean`                                             | Whether to search while typing                             | `true`               |
+| allowClear      | `boolean`                                             | Whether allow clear                                        | `true`               |
+| closable        | `boolean`                                             | Whether tags are closable                                  | `true`               |
+| placeholder     | `string`                                              | Placeholder text                                           | -                    |
+| optionLabelProp | `string \| ((option: TableSelectDataType) => string)` | Option label property                                      | `'name'`             |
+| type            | `'radio' \| 'checkbox'`                               | Selection type                                             | `'radio'`            |
+| options         | `TagType[]`                                           | Preset options                                             | -                    |
+| isShowFilter    | `boolean`                                             | Whether to show filter (All/Selected for multiple)         | `true`               |
+| containerId     | `string`                                              | Container ID (for popup mounting)                          | -                    |
+| io              | `'out'`                                               | Input direction                                            | -                    |
+| onChange        | `(keys, data, checked, changeData) => void`           | Selection change callback                                  | -                    |
+| onSearch        | `(value: string, e?) => void`                         | Search callback                                            | -                    |
+| onOpenChange    | `(open: boolean) => void`                             | Popup state change callback                                | -                    |
 
 ### RowSelectionType
 
 Row selection configuration, inherited from Table component's RowSelectionType.
 
-| Property | Type | Description | Default Value |
-| --- | --- | --- | --- |
-| type | `'radio' \| 'checkbox'` | Single/multiple selection | - |
-| selectedRowKeys | `Array<SelectionKeyType> \| SelectionKeyType` | (Controlled) selected row keys | - |
-| defaultSelectedRowKeys | `Array<SelectionKeyType> \| SelectionKeyType` | Default selected row keys | - |
-| onChange | `(selectedRowKeys, selectedRows) => void` | Callback when selection changes | - |
+| Property               | Type                                          | Description                     | Default Value |
+| ---------------------- | --------------------------------------------- | ------------------------------- | ------------- |
+| type                   | `'radio' \| 'checkbox'`                       | Single/multiple selection       | -             |
+| selectedRowKeys        | `Array<SelectionKeyType> \| SelectionKeyType` | (Controlled) selected row keys  | -             |
+| defaultSelectedRowKeys | `Array<SelectionKeyType> \| SelectionKeyType` | Default selected row keys       | -             |
+| onChange               | `(selectedRowKeys, selectedRows) => void`     | Callback when selection changes | -             |
 
 ## Methods
 
@@ -77,17 +77,20 @@ Row selection configuration, inherited from Table component's RowSelectionType.
 
 InternalTable is an internal component of TableSelect and typically doesn't need to be used directly.
 
-| Property | Type | Description | Default Value |
-| --- | --- | --- | --- |
-| rowKey | `string` | Unique identifier field name for data | - |
-| columns | `Array<any>` | Table column configuration | - |
-| dataSource | `Array<InDataType>` | Data source | - |
-| rowSelection | `RowSelectionType` | Row selection configuration | - |
-| type | `'radio' \| 'checkbox'` | Selection type | - |
-| value | `SelectedKeyType \| Array<SelectedKeyType>` | Selected value | - |
-| isShowFilter | `boolean` | Whether to show filter | `true` |
-| visible | `boolean` | Whether popup is visible | - |
+| Property     | Type                                        | Description                                                            | Default Value |
+| ------------ | ------------------------------------------- | ---------------------------------------------------------------------- | ------------- |
+| rowKey       | `string`                                    | Unique identifier field name for data                                  | -             |
+| columns      | `Array<any>`                                | Table column configuration                                             | -             |
+| dataSource   | `Array<TableSelectDataType>`                | Data source                                                            | -             |
+| rowSelection | `RowSelectionType`                          | Row selection configuration                                            | -             |
+| type         | `'radio' \| 'checkbox'`                     | Selection type                                                         | -             |
+| value        | `SelectedKeyType \| Array<SelectedKeyType>` | Selected value                                                         | -             |
+| isShowFilter | `boolean`                                   | Whether to show filter                                                 | `true`        |
+| visible      | `boolean`                                   | Whether popup is visible                                               | -             |
+| popupRef     | `React.RefObject<HTMLDivElement \| null>`   | Ref to the popup root element, used internally for keyboard navigation | -             |
 
 ## Notes
 
+- When the dropdown is open, keyboard is supported: `↑`/`↓` move the highlight across rows, `Space` selects/toggles the highlighted row, `Esc` closes the dropdown; the text caret always stays in the input; press `Enter` while closed to open the dropdown
+
 - Adapted for mobile (popup constrained with max-width/height and scrollable)

package/src/TableSelect/index.zh-CN.md

@@ -31,45 +31,45 @@ toc: 'content'
 
 ### TableSelectProps
 
-| 属性名 | 类型 | 描述 | 默认值 |
-| --- | --- | --- | --- |
-| prefixCls | `string` | 自定义类名前缀 | `'yee-table-select'` |
-| className | `string` | 根元素类名 | - |
-| style | `React.CSSProperties` | 根元素行内样式 | - |
-| rowKey | `string \| ((record: any) => string)` | 数据的唯一标识字段名 | `'id'` |
-| columns | `Array<any>` | 表格列的配置信息 | - |
-| dataSource | `Array<InDataType>` | 数据源 | - |
-| rowSelection | `RowSelectionType` | 行选择配置 | - |
-| value | `SelectionKeyType \| SelectionKeyType[]` | 受控值 | - |
-| defaultValue | `SelectionKeyType \| SelectionKeyType[]` | 默认值 | - |
-| disabled | `boolean` | 是否禁用 | - |
-| loading | `boolean` | 是否处于加载状态，加载时显示灰色加载图标 | `false` |
-| placement | `'bottomLeft' \| 'topLeft'` | 弹出层位置 | `'bottomLeft'` |
-| searchable | `boolean` | 是否可搜索 | `true` |
-| searchOnInput | `boolean` | 是否边输入边搜索 | `true` |
-| allowClear | `boolean` | 是否允许清除 | `true` |
-| closable | `boolean` | 标签是否可关闭 | `true` |
-| placeholder | `string` | 占位符文本 | - |
-| optionLabelProp | `string \| ((option: InDataType) => string)` | 选项标签属性 | `'name'` |
-| type | `'radio' \| 'checkbox'` | 选择类型 | `'radio'` |
-| options | `TagType[]` | 预设选项 | - |
-| isShowFilter | `boolean` | 是否显示过滤器(多选时 All/Selected) | `true` |
-| containerId | `string` | 容器 ID(用于弹出层挂载) | - |
-| io | `'out'` | 输入方向 | - |
-| onChange | `(keys, data, checked, changeData) => void` | 选中变更回调 | - |
-| onSearch | `(value: string, e?) => void` | 搜索回调 | - |
-| onOpenChange | `(open: boolean) => void` | 弹出层状态变更回调 | - |
+| 属性名          | 类型                                                  | 描述                                     | 默认值               |
+| --------------- | ----------------------------------------------------- | ---------------------------------------- | -------------------- |
+| prefixCls       | `string`                                              | 自定义类名前缀                           | `'yee-table-select'` |
+| className       | `string`                                              | 根元素类名                               | -                    |
+| style           | `React.CSSProperties`                                 | 根元素行内样式                           | -                    |
+| rowKey          | `string \| ((record: any) => string)`                 | 数据的唯一标识字段名                     | `'id'`               |
+| columns         | `Array<any>`                                          | 表格列的配置信息                         | -                    |
+| dataSource      | `Array<TableSelectDataType>`                          | 数据源                                   | -                    |
+| rowSelection    | `RowSelectionType`                                    | 行选择配置                               | -                    |
+| value           | `SelectionKeyType \| SelectionKeyType[]`              | 受控值                                   | -                    |
+| defaultValue    | `SelectionKeyType \| SelectionKeyType[]`              | 默认值                                   | -                    |
+| disabled        | `boolean`                                             | 是否禁用                                 | -                    |
+| loading         | `boolean`                                             | 是否处于加载状态，加载时显示灰色加载图标 | `false`              |
+| placement       | `'bottomLeft' \| 'topLeft'`                           | 弹出层位置                               | `'bottomLeft'`       |
+| searchable      | `boolean`                                             | 是否可搜索                               | `true`               |
+| searchOnInput   | `boolean`                                             | 是否边输入边搜索                         | `true`               |
+| allowClear      | `boolean`                                             | 是否允许清除                             | `true`               |
+| closable        | `boolean`                                             | 标签是否可关闭                           | `true`               |
+| placeholder     | `string`                                              | 占位符文本                               | -                    |
+| optionLabelProp | `string \| ((option: TableSelectDataType) => string)` | 选项标签属性                             | `'name'`             |
+| type            | `'radio' \| 'checkbox'`                               | 选择类型                                 | `'radio'`            |
+| options         | `TagType[]`                                           | 预设选项                                 | -                    |
+| isShowFilter    | `boolean`                                             | 是否显示过滤器(多选时 All/Selected)      | `true`               |
+| containerId     | `string`                                              | 容器 ID(用于弹出层挂载)                  | -                    |
+| io              | `'out'`                                               | 输入方向                                 | -                    |
+| onChange        | `(keys, data, checked, changeData) => void`           | 选中变更回调                             | -                    |
+| onSearch        | `(value: string, e?) => void`                         | 搜索回调                                 | -                    |
+| onOpenChange    | `(open: boolean) => void`                             | 弹出层状态变更回调                       | -                    |
 
 ### RowSelectionType
 
 表格行选择配置，继承自 Table 组件的 RowSelectionType。
 
-| 属性名 | 类型 | 描述 | 默认值 |
-| --- | --- | --- | --- |
-| type | `'radio' \| 'checkbox'` | 单选/多选 | - |
-| selectedRowKeys | `Array<SelectionKeyType> \| SelectionKeyType` | (受控)选中的行keys | - |
-| defaultSelectedRowKeys | `Array<SelectionKeyType> \| SelectionKeyType` | 默认选中的行keys | - |
-| onChange | `(selectedRowKeys, selectedRows) => void` | 选中项发生变化时的回调 | - |
+| 属性名                 | 类型                                          | 描述                   | 默认值 |
+| ---------------------- | --------------------------------------------- | ---------------------- | ------ |
+| type                   | `'radio' \| 'checkbox'`                       | 单选/多选              | -      |
+| selectedRowKeys        | `Array<SelectionKeyType> \| SelectionKeyType` | (受控)选中的行keys     | -      |
+| defaultSelectedRowKeys | `Array<SelectionKeyType> \| SelectionKeyType` | 默认选中的行keys       | -      |
+| onChange               | `(selectedRowKeys, selectedRows) => void`     | 选中项发生变化时的回调 | -      |
 
 ## 方法
 
@@ -77,17 +77,20 @@ toc: 'content'
 
 InternalTable 组件是 TableSelect 的内部组件，通常不需要直接使用。
 
-| 属性名 | 类型 | 描述 | 默认值 |
-| --- | --- | --- | --- |
-| rowKey | `string` | 数据的唯一标识字段名 | - |
-| columns | `Array<any>` | 表格列的配置信息 | - |
-| dataSource | `Array<InDataType>` | 数据源 | - |
-| rowSelection | `RowSelectionType` | 行选择配置 | - |
-| type | `'radio' \| 'checkbox'` | 选择类型 | - |
-| value | `SelectedKeyType \| Array<SelectedKeyType>` | 选中的值 | - |
-| isShowFilter | `boolean` | 是否显示过滤器 | `true` |
-| visible | `boolean` | 弹出层是否可见 | - |
+| 属性名       | 类型                                        | 描述                               | 默认值 |
+| ------------ | ------------------------------------------- | ---------------------------------- | ------ |
+| rowKey       | `string`                                    | 数据的唯一标识字段名               | -      |
+| columns      | `Array<any>`                                | 表格列的配置信息                   | -      |
+| dataSource   | `Array<TableSelectDataType>`                | 数据源                             | -      |
+| rowSelection | `RowSelectionType`                          | 行选择配置                         | -      |
+| type         | `'radio' \| 'checkbox'`                     | 选择类型                           | -      |
+| value        | `SelectedKeyType \| Array<SelectedKeyType>` | 选中的值                           | -      |
+| isShowFilter | `boolean`                                   | 是否显示过滤器                     | `true` |
+| visible      | `boolean`                                   | 弹出层是否可见                     | -      |
+| popupRef     | `React.RefObject<HTMLDivElement \| null>`   | 弹层根元素 ref，供键盘导航内部使用 | -      |
 
 ## 注意事项
 
+- 下拉展开后支持键盘操作：`↑`/`↓` 在行间移动高亮，`空格` 选中/取消勾选高亮行，`Esc` 关闭下拉；输入光标始终保留在输入框内；收起时按 `回车` 可展开下拉
+
 - 已适配移动端（弹窗限制最大宽高并支持滚动）

package/src/TableSelect/interface.ts

@@ -10,7 +10,7 @@ type SelectedKeyType = string | number;
 /**
  * Data item type
  */
-type InDataType = {
+export type TableSelectDataType = {
   [propName: string]: any;
 };
 
@@ -42,7 +42,7 @@ export interface InternalTableProps {
   /**
    * Data source
    */
-  dataSource: Array<InDataType>;
+  dataSource: Array<TableSelectDataType>;
   /**
    * Custom class name
    */
@@ -67,6 +67,11 @@ export interface InternalTableProps {
    * Whether popup is visible (for focus trap)
    */
   visible?: boolean;
+  /**
+   * Ref to the popup root element, used by TableSelect for keyboard navigation
+   * @internal
+   */
+  popupRef?: React.RefObject<HTMLDivElement | null>;
 }
 
 /**
@@ -96,7 +101,7 @@ export interface TableSelectProps
   /**
    * Data source
    */
-  dataSource: Array<InDataType>;
+  dataSource: Array<TableSelectDataType>;
   /**
    * Single or multiple selection
    * @default: 'radio'
@@ -180,7 +185,7 @@ export interface TableSelectProps
    * Option label property (text field for displaying labels)
    * @default 'name'
    */
-  optionLabelProp?: string | ((option: InDataType) => string);
+  optionLabelProp?: string | ((option: TableSelectDataType) => string);
   /**
    * Selection change callback
    * @param keys Selected keys