@fangxinyan/lumina 0.6.9 → 0.6.10

package/dist/{Table-IYJTPY6J.css → Table-5XJNZWLF.css}

@@ -69,11 +69,27 @@
 /* Card-row variant: each row is its own raised pill */
 .table.cards {
   border-collapse: separate;
-  border-spacing: 0 10px;
-  padding: 10px;
+  border-spacing: 0 14px;
+  padding: 12px;
   background: transparent;
   box-shadow: none;
 }
+.table.cards tbody tr {
+  position: relative;
+  isolation: isolate;
+  transition: transform var(--dur-fast) var(--ease);
+}
+.table.cards tbody tr::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: 0;
+  border-radius: var(--r-md);
+  background: var(--bg);
+  box-shadow: var(--neu-shadow-control);
+  pointer-events: none;
+  transition: box-shadow var(--dur-fast) var(--ease), transform var(--dur-fast) var(--ease);
+}
 .table.cards thead th {
   background: transparent;
   border-bottom: none;
@@ -81,22 +97,24 @@
   padding-bottom: 6px;
 }
 .table.cards tbody td {
-  background: var(--bg);
+  position: relative;
+  z-index: 1;
+  background: transparent;
   border-bottom: none;
   padding: 14px 18px;
+  box-shadow: none;
 }
 .table.cards tbody td:first-child {
   border-radius: var(--r-md) 0 0 var(--r-md);
-  box-shadow: -4px 4px 8px var(--shadow-dark), -4px -4px 8px var(--shadow-light);
 }
 .table.cards tbody td:last-child {
   border-radius: 0 var(--r-md) var(--r-md) 0;
-  box-shadow: 4px 4px 8px var(--shadow-dark), 4px -4px 8px var(--shadow-light);
 }
-.table.cards tbody td:not(:first-child):not(:last-child) {
-  box-shadow: 0 4px 8px var(--shadow-dark), 0 -4px 8px var(--shadow-light);
+.table.cards.hoverable tbody tr:hover {
+  transform: translateY(-1px);
 }
-.table.cards.hoverable tbody tr:hover td { background: var(--bg); transform: translateY(-1px); }
+.table.cards.hoverable tbody tr:hover::before { box-shadow: var(--neu-shadow-panel); }
+.table.cards.hoverable tbody tr:hover td { background: transparent; }
 
 .table .row-check { width: 44px; }
 .table .row-check .checkbox { display: inline-flex; }

package/dist/Table.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkCPBFUKSX_cjs = require('./chunk-CPBFUKSX.cjs');
+var chunkPPDPKPLE_cjs = require('./chunk-PPDPKPLE.cjs');
 require('./chunk-XVDD6JEU.cjs');
 require('./chunk-F65KYGPX.cjs');
 require('./chunk-76OH42CM.cjs');
@@ -14,5 +14,5 @@ require('./chunk-GJAEGIPM.cjs');
 
 Object.defineProperty(exports, "Table", {
   enumerable: true,
-  get: function () { return chunkCPBFUKSX_cjs.Table; }
+  get: function () { return chunkPPDPKPLE_cjs.Table; }
 });

package/dist/Table.d.cts

@@ -43,11 +43,11 @@ interface PaginationConfig {
     total?: number;
     /** Fired when user picks a page or changes page size. */
     onChange?: (page: number, pageSize: number) => void;
-    /** Reserved for future: jump-to-page input. */
+    /** Show a jump-to-page input. */
     showQuickJumper?: boolean;
-    /** Reserved for future: page size dropdown. */
+    /** Show a page size dropdown. */
     showSizeChanger?: boolean;
-    /** Reserved for future: selectable page sizes. */
+    /** Selectable page sizes for the size dropdown. */
     pageSizeOptions?: number[];
 }
 interface RowSelectionConfig<Row = any> {

package/dist/Table.d.ts

@@ -43,11 +43,11 @@ interface PaginationConfig {
     total?: number;
     /** Fired when user picks a page or changes page size. */
     onChange?: (page: number, pageSize: number) => void;
-    /** Reserved for future: jump-to-page input. */
+    /** Show a jump-to-page input. */
     showQuickJumper?: boolean;
-    /** Reserved for future: page size dropdown. */
+    /** Show a page size dropdown. */
     showSizeChanger?: boolean;
-    /** Reserved for future: selectable page sizes. */
+    /** Selectable page sizes for the size dropdown. */
     pageSizeOptions?: number[];
 }
 interface RowSelectionConfig<Row = any> {

package/dist/Table.js

@@ -1,4 +1,4 @@
-export { Table } from './chunk-FZITSOKH.js';
+export { Table } from './chunk-QMZBOB7Q.js';
 import './chunk-5CWTC3I2.js';
 import './chunk-MOLKLUSQ.js';
 import './chunk-I5XCHN67.js';

package/dist/{TablePro-JRSBPXB5.css → TablePro-3NGWERWT.css}

@@ -11,7 +11,7 @@
   margin-top: 0;
   padding: 6px 16px;
   border-top: 1px solid var(--divider);
-  background: color-mix(in oklch, var(--bg-sunken) 30%, transparent);
+  background: transparent;
 }
 .table-toolbar {
   display: flex;
@@ -41,5 +41,5 @@
 .table-footer {
   padding: 10px 16px;
   border-top: 1px solid var(--divider);
-  background: color-mix(in oklch, var(--bg-sunken) 30%, transparent);
+  background: transparent;
 }

package/dist/TablePro.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkNUNPFMCM_cjs = require('./chunk-NUNPFMCM.cjs');
-require('./chunk-CPBFUKSX.cjs');
+var chunkJ2KV6K23_cjs = require('./chunk-J2KV6K23.cjs');
+require('./chunk-PPDPKPLE.cjs');
 require('./chunk-XVDD6JEU.cjs');
 require('./chunk-F65KYGPX.cjs');
 require('./chunk-76OH42CM.cjs');
@@ -15,5 +15,5 @@ require('./chunk-GJAEGIPM.cjs');
 
 Object.defineProperty(exports, "TablePro", {
   enumerable: true,
-  get: function () { return chunkNUNPFMCM_cjs.TablePro; }
+  get: function () { return chunkJ2KV6K23_cjs.TablePro; }
 });

package/dist/TablePro.js

@@ -1,5 +1,5 @@
-export { TablePro } from './chunk-N24KHD5B.js';
-import './chunk-FZITSOKH.js';
+export { TablePro } from './chunk-KWIHEE4D.js';
+import './chunk-QMZBOB7Q.js';
 import './chunk-5CWTC3I2.js';
 import './chunk-MOLKLUSQ.js';
 import './chunk-I5XCHN67.js';

package/dist/{chunk-NUNPFMCM.cjs → chunk-J2KV6K23.cjs}

@@ -1,9 +1,9 @@
 'use strict';
 
-var chunkCPBFUKSX_cjs = require('./chunk-CPBFUKSX.cjs');
+var chunkPPDPKPLE_cjs = require('./chunk-PPDPKPLE.cjs');
 require('./tokens-RGFJKRC7.css');
 require('./shared-NJHRNLRH.css');
-require('./TablePro-JRSBPXB5.css');
+require('./TablePro-3NGWERWT.css');
 var React = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 
@@ -71,7 +71,7 @@ var TableProInner = ({
           actions && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "table-toolbar-actions", children: actions })
         ] }),
         /* @__PURE__ */ jsxRuntime.jsx(
-          chunkCPBFUKSX_cjs.Table,
+          chunkPPDPKPLE_cjs.Table,
           {
             columns,
             data,

package/dist/{chunk-N24KHD5B.js → chunk-KWIHEE4D.js}

@@ -1,7 +1,7 @@
-import { Table } from './chunk-FZITSOKH.js';
+import { Table } from './chunk-QMZBOB7Q.js';
 import './tokens-RGFJKRC7.css';
 import './shared-NJHRNLRH.css';
-import './TablePro-JRSBPXB5.css';
+import './TablePro-3NGWERWT.css';
 import * as React from 'react';
 import { jsxs, jsx } from 'react/jsx-runtime';
 

package/dist/{chunk-CPBFUKSX.cjs → chunk-PPDPKPLE.cjs}

@@ -6,7 +6,7 @@ var chunkYB3IWIOJ_cjs = require('./chunk-YB3IWIOJ.cjs');
 var chunkGJAEGIPM_cjs = require('./chunk-GJAEGIPM.cjs');
 require('./tokens-RGFJKRC7.css');
 require('./shared-NJHRNLRH.css');
-require('./Table-IYJTPY6J.css');
+require('./Table-5XJNZWLF.css');
 var React = require('react');
 var reactDom = require('react-dom');
 var jsxRuntime = require('react/jsx-runtime');
@@ -159,10 +159,21 @@ var TableInner = ({
     const start = (curPage - 1) * curPageSize;
     return filteredData.slice(start, start + curPageSize);
   }, [pagEnabled, filteredData, curPage, curPageSize, pagCfg.total, pageControlled]);
+  const skipNextPaginationChangeRef = React__namespace.useRef(false);
   const onPageChange = (p) => {
+    if (skipNextPaginationChangeRef.current) {
+      skipNextPaginationChangeRef.current = false;
+      return;
+    }
     if (!pageControlled) setInnerPage(p);
     pagCfg.onChange?.(p, curPageSize);
   };
+  const onPageSizeChange = (_current, size) => {
+    skipNextPaginationChangeRef.current = true;
+    if (!pageControlled) setInnerPage(1);
+    if (pagCfg.pageSize === void 0) setInnerPageSize(size);
+    pagCfg.onChange?.(1, size);
+  };
   const [innerExpanded, setInnerExpanded] = React__namespace.useState(
     expandable?.defaultExpandedRowKeys ?? []
   );
@@ -381,7 +392,11 @@ var TableInner = ({
         total: totalCount,
         pageSize: curPageSize,
         page: curPage,
-        onChange: onPageChange
+        onChange: onPageChange,
+        showQuickJumper: pagCfg.showQuickJumper,
+        showSizeChanger: pagCfg.showSizeChanger,
+        pageSizeOptions: pagCfg.pageSizeOptions,
+        onShowSizeChange: onPageSizeChange
       }
     ) })
   ] });

package/dist/{chunk-FZITSOKH.js → chunk-QMZBOB7Q.js}

@@ -4,7 +4,7 @@ import { useFloating } from './chunk-DUFRASGO.js';
 import { Icon } from './chunk-SNX4FZYB.js';
 import './tokens-RGFJKRC7.css';
 import './shared-NJHRNLRH.css';
-import './Table-IYJTPY6J.css';
+import './Table-5XJNZWLF.css';
 import * as React from 'react';
 import { createPortal } from 'react-dom';
 import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
@@ -137,10 +137,21 @@ var TableInner = ({
     const start = (curPage - 1) * curPageSize;
     return filteredData.slice(start, start + curPageSize);
   }, [pagEnabled, filteredData, curPage, curPageSize, pagCfg.total, pageControlled]);
+  const skipNextPaginationChangeRef = React.useRef(false);
   const onPageChange = (p) => {
+    if (skipNextPaginationChangeRef.current) {
+      skipNextPaginationChangeRef.current = false;
+      return;
+    }
     if (!pageControlled) setInnerPage(p);
     pagCfg.onChange?.(p, curPageSize);
   };
+  const onPageSizeChange = (_current, size) => {
+    skipNextPaginationChangeRef.current = true;
+    if (!pageControlled) setInnerPage(1);
+    if (pagCfg.pageSize === void 0) setInnerPageSize(size);
+    pagCfg.onChange?.(1, size);
+  };
   const [innerExpanded, setInnerExpanded] = React.useState(
     expandable?.defaultExpandedRowKeys ?? []
   );
@@ -359,7 +370,11 @@ var TableInner = ({
         total: totalCount,
         pageSize: curPageSize,
         page: curPage,
-        onChange: onPageChange
+        onChange: onPageChange,
+        showQuickJumper: pagCfg.showQuickJumper,
+        showSizeChanger: pagCfg.showSizeChanger,
+        pageSizeOptions: pagCfg.pageSizeOptions,
+        onShowSizeChange: onPageSizeChange
       }
     ) })
   ] });

package/dist/index.cjs

@@ -12,8 +12,8 @@ var chunk4LOOWTRX_cjs = require('./chunk-4LOOWTRX.cjs');
 require('./chunk-6EOSMK34.cjs');
 var chunkDGB6KVU3_cjs = require('./chunk-DGB6KVU3.cjs');
 var chunkHFM4YKM5_cjs = require('./chunk-HFM4YKM5.cjs');
-var chunkNUNPFMCM_cjs = require('./chunk-NUNPFMCM.cjs');
-var chunkCPBFUKSX_cjs = require('./chunk-CPBFUKSX.cjs');
+var chunkJ2KV6K23_cjs = require('./chunk-J2KV6K23.cjs');
+var chunkPPDPKPLE_cjs = require('./chunk-PPDPKPLE.cjs');
 var chunkZ35Q432P_cjs = require('./chunk-Z35Q432P.cjs');
 var chunkZGDAYWWC_cjs = require('./chunk-ZGDAYWWC.cjs');
 var chunkXVDD6JEU_cjs = require('./chunk-XVDD6JEU.cjs');
@@ -51,7 +51,7 @@ var chunkHTW62OMX_cjs = require('./chunk-HTW62OMX.cjs');
 var chunkGJAEGIPM_cjs = require('./chunk-GJAEGIPM.cjs');
 
 // src/index.ts
-var VERSION = "0.6.9";
+var VERSION = "0.6.10";
 
 Object.defineProperty(exports, "Tabs", {
   enumerable: true,
@@ -167,11 +167,11 @@ Object.defineProperty(exports, "Switch", {
 });
 Object.defineProperty(exports, "TablePro", {
   enumerable: true,
-  get: function () { return chunkNUNPFMCM_cjs.TablePro; }
+  get: function () { return chunkJ2KV6K23_cjs.TablePro; }
 });
 Object.defineProperty(exports, "Table", {
   enumerable: true,
-  get: function () { return chunkCPBFUKSX_cjs.Table; }
+  get: function () { return chunkPPDPKPLE_cjs.Table; }
 });
 Object.defineProperty(exports, "MessageContainer", {
   enumerable: true,

package/dist/index.d.cts

@@ -49,6 +49,6 @@ import 'react/jsx-runtime';
 import 'react';
 
 /** Package version — bumped by release scripts. */
-declare const VERSION = "0.6.9";
+declare const VERSION = "0.6.10";
 
 export { VERSION };

package/dist/index.d.ts

@@ -49,6 +49,6 @@ import 'react/jsx-runtime';
 import 'react';
 
 /** Package version — bumped by release scripts. */
-declare const VERSION = "0.6.9";
+declare const VERSION = "0.6.10";
 
 export { VERSION };

package/dist/index.js

@@ -10,8 +10,8 @@ export { SURFACE_THEME_PRESETS, Surface } from './chunk-WIZVOZNO.js';
 import './chunk-6SPMHY54.js';
 export { ACCENT_PRESETS, ACCENT_PRESETS_DARK, FONT_STACKS, ThemeProvider, applyTheme, normalizeAccentInput, resolveThemeColorScheme, resolveThemeMode, useTheme, useThemeOptional } from './chunk-7ZCTEIOW.js';
 export { Switch } from './chunk-6VSNO7IH.js';
-export { TablePro } from './chunk-N24KHD5B.js';
-export { Table } from './chunk-FZITSOKH.js';
+export { TablePro } from './chunk-KWIHEE4D.js';
+export { Table } from './chunk-QMZBOB7Q.js';
 export { MessageContainer, ToastContainer, message, toast } from './chunk-62RPBEAW.js';
 export { Modal } from './chunk-SGNDIRZC.js';
 export { Pagination } from './chunk-5CWTC3I2.js';
@@ -49,6 +49,6 @@ export { Calendar } from './chunk-W72IIGOV.js';
 export { AimOutlined, AppstoreOutlined, BarChartOutlined, BlockOutlined, BorderOutlined, CameraOutlined, CaretDownOutlined, CaretUpOutlined, CheckCircleFilled, CheckCircleOutlined, CheckOutlined, ClockCircleFilled, CloseCircleOutlined, CloseOutlined, CopyOutlined, DashboardOutlined, DeleteOutlined, DownOutlined, EnvironmentOutlined, ExclamationCircleOutlined, FolderOpenOutlined, ICON_NAMES, Icon, LeftOutlined, LoadingOutlined, MinusCircleOutlined, MinusOutlined, NAMED_ICON_MAP, PictureOutlined, PlusOutlined, QqOutlined, ReloadOutlined, RightOutlined, RobotOutlined, SearchOutlined, SettingOutlined, StarFilled, StarOutlined, SwapOutlined, SwapRightOutlined, SyncOutlined, ThunderboltOutlined, TranslationOutlined, UnorderedListOutlined, UserOutlined, isIconName, renderIconSlot, resolveIconName } from './chunk-SNX4FZYB.js';
 
 // src/index.ts
-var VERSION = "0.6.9";
+var VERSION = "0.6.10";
 
 export { VERSION };

package/dist/styles.css

@@ -2093,11 +2093,27 @@ input, textarea, select { font-family: inherit; color: inherit; }
 /* Card-row variant: each row is its own raised pill */
 .table.cards {
   border-collapse: separate;
-  border-spacing: 0 10px;
-  padding: 10px;
+  border-spacing: 0 14px;
+  padding: 12px;
   background: transparent;
   box-shadow: none;
 }
+.table.cards tbody tr {
+  position: relative;
+  isolation: isolate;
+  transition: transform var(--dur-fast) var(--ease);
+}
+.table.cards tbody tr::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: 0;
+  border-radius: var(--r-md);
+  background: var(--bg);
+  box-shadow: var(--neu-shadow-control);
+  pointer-events: none;
+  transition: box-shadow var(--dur-fast) var(--ease), transform var(--dur-fast) var(--ease);
+}
 .table.cards thead th {
   background: transparent;
   border-bottom: none;
@@ -2105,22 +2121,24 @@ input, textarea, select { font-family: inherit; color: inherit; }
   padding-bottom: 6px;
 }
 .table.cards tbody td {
-  background: var(--bg);
+  position: relative;
+  z-index: 1;
+  background: transparent;
   border-bottom: none;
   padding: 14px 18px;
+  box-shadow: none;
 }
 .table.cards tbody td:first-child {
   border-radius: var(--r-md) 0 0 var(--r-md);
-  box-shadow: -4px 4px 8px var(--shadow-dark), -4px -4px 8px var(--shadow-light);
 }
 .table.cards tbody td:last-child {
   border-radius: 0 var(--r-md) var(--r-md) 0;
-  box-shadow: 4px 4px 8px var(--shadow-dark), 4px -4px 8px var(--shadow-light);
 }
-.table.cards tbody td:not(:first-child):not(:last-child) {
-  box-shadow: 0 4px 8px var(--shadow-dark), 0 -4px 8px var(--shadow-light);
+.table.cards.hoverable tbody tr:hover {
+  transform: translateY(-1px);
 }
-.table.cards.hoverable tbody tr:hover td { background: var(--bg); transform: translateY(-1px); }
+.table.cards.hoverable tbody tr:hover::before { box-shadow: var(--neu-shadow-panel); }
+.table.cards.hoverable tbody tr:hover td { background: transparent; }
 .table .row-check { width: 44px; }
 .table .row-check .checkbox { display: inline-flex; }
 .table .row-expand { width: 40px; text-align: center; }
@@ -2270,7 +2288,7 @@ input, textarea, select { font-family: inherit; color: inherit; }
   margin-top: 0;
   padding: 6px 16px;
   border-top: 1px solid var(--divider);
-  background: color-mix(in oklch, var(--bg-sunken) 30%, transparent);
+  background: transparent;
 }
 .table-toolbar {
   display: flex;
@@ -2300,7 +2318,7 @@ input, textarea, select { font-family: inherit; color: inherit; }
 .table-footer {
   padding: 10px 16px;
   border-top: 1px solid var(--divider);
-  background: color-mix(in oklch, var(--bg-sunken) 30%, transparent);
+  background: transparent;
 }
 /* ============ Pagination ============ */
 .pagination {

package/docs/llms/table.md

@@ -16,13 +16,14 @@ import { Table } from "@fangxinyan/lumina";
 <Table rowKey="id" columns={[...]} data={data} />
 ```
 
-### 样式变体
+### 样式变体 / hover
 
-三种视觉变体:striped (条纹)、embossed (凸起)、cards (卡片行)。
+覆盖 variant 的四个取值,以及 striped 快捷属性和 hoverable 关闭状态。
 
 ```tsx
-<Table variant="striped" ... />
-<Table variant="embossed" ... />
+<Table variant="default" ... />
+<Table striped ... />
+<Table variant="embossed" hoverable={false} ... />
 <Table variant="cards" ... />
 ```
 
@@ -34,11 +35,38 @@ import { Table } from "@fangxinyan/lumina";
 <Table
   rowKey="id"
   columns={[...]}
-  data={data}               // 24 rows
+  data={data}
   pagination={{ pageSize: 6 }}
 />
 ```
 
+### 分页配置
+
+覆盖 current / defaultCurrent / pageSize / defaultPageSize / total / onChange / showQuickJumper / showSizeChanger / pageSizeOptions。
+
+```tsx
+<Table
+  data={serverPageData}
+  pagination={{
+    current,
+    pageSize,
+    total: allRows.length,
+    showQuickJumper: true,
+    showSizeChanger: true,
+    pageSizeOptions: [4, 5, 8],
+    onChange: (page, nextPageSize) => {
+      setCurrent(page);
+      setPageSize(nextPageSize);
+    },
+  }}
+/>
+
+<Table
+  data={allRows}
+  pagination={{ defaultCurrent: 2, defaultPageSize: 4 }}
+/>
+```
+
 ### 固定表头 / 横向滚动
 
 scroll.y 固定表头并限制表体最大高度;scroll.x 设置内容最小宽度。
@@ -51,15 +79,35 @@ scroll.y 固定表头并限制表体最大高度;scroll.x 设置内容最小宽
 />
 ```
 
+### 受控排序 / 行点击
+
+Table 负责渲染排序指示,排序后的 data 由外部状态计算后传入。
+
+```tsx
+<Table
+  sortKey={sortKey}
+  sortDir={sortDir}
+  onSort={(key) => {
+    setSortKey(key);
+    setSortDir((dir) => (dir === "asc" ? "desc" : "asc"));
+  }}
+  onRowClick={(row, index) => setClicked(row.name)}
+  columns={[{ key: "salary", sortable: true, align: "right" }]}
+/>
+```
+
 ### 行选择 (rowSelection)
 
-rowSelection 提供表头全选、半选状态与按行禁用能力。
+rowSelection 提供表头全选、半选状态、受控选中项、回传选中行与按行禁用能力。
 
 ```tsx
 <Table
   rowSelection={{
     selectedRowKeys,
-    onChange: (keys, rows) => setSelectedKeys(keys),
+    onChange: (keys, rows) => {
+      setSelectedKeys(keys);
+      setSelectedRows(rows);
+    },
     getCheckboxProps: (row) => ({ disabled: row.status === "离线" }),
   }}
   columns={[...]}
@@ -69,7 +117,7 @@ rowSelection 提供表头全选、半选状态与按行禁用能力。
 
 ### 行选择 · 单选
 
-设置 rowSelection.type = 'radio' 变成单选模式。
+设置 rowSelection.type = 'radio' 变成单选模式,defaultSelectedRowKeys 设置非受控初始值。
 
 ```tsx
 <Table
@@ -79,14 +127,29 @@ rowSelection 提供表头全选、半选状态与按行禁用能力。
 />
 ```
 
+### 旧版选择 API
+
+selectable / selected / onSelect 保留向后兼容,新代码优先使用 rowSelection。
+
+```tsx
+<Table
+  selectable
+  selected={selected}
+  onSelect={setSelected}
+  columns={[...]}
+  data={data}
+/>
+```
+
 ### 可展开行
 
-点击左侧箭头按钮展开/收起,在行下方渲染自定义内容。
+点击左侧箭头按钮展开/收起,defaultExpandedRowKeys 设置非受控初始展开。
 
 ```tsx
 <Table
   expandable={{
-    expandedRowRender: (row) => <div>…详情…</div>,
+    defaultExpandedRowKeys: [1],
+    expandedRowRender: (row) => <div>...详情...</div>,
     rowExpandable: (row) => row.status !== "离线",
   }}
   columns={[...]}
@@ -94,19 +157,36 @@ rowSelection 提供表头全选、半选状态与按行禁用能力。
 />
 ```
 
+### 受控展开
+
+expandedRowKeys 由外部状态控制,onExpand 负责同步展开 key。
+
+```tsx
+<Table
+  expandable={{
+    expandedRowKeys,
+    onExpand: (expanded, row) => setExpandedRowKeys(...),
+    expandedRowRender: (row) => <div>...</div>,
+  }}
+/>
+```
+
 ### 列筛选
 
-在列上配置 filters 即可在列头显示漏斗图标;点击弹出勾选面板,勾选后过滤数据。
+filters + onFilter 生成列头筛选菜单;defaultFilteredValue 可设置非受控初始筛选。
 
 ```tsx
 <Table
   columns={[
     {
-      key: "role", title: "部门", dataIndex: "role",
+      key: "role",
+      title: "部门",
+      dataIndex: "role",
       filters: [
         { text: "设计", value: "设计" },
         { text: "研发", value: "研发" },
       ],
+      defaultFilteredValue: ["研发"],
       onFilter: (value, row) => row.role === value,
     },
   ]}
@@ -114,6 +194,41 @@ rowSelection 提供表头全选、半选状态与按行禁用能力。
 />
 ```
 
+### 受控筛选值
+
+filteredValue 由外部状态控制,适合和工具栏筛选器或 URL 状态同步。
+
+```tsx
+<Table
+  columns={[
+    {
+      key: "status",
+      filteredValue,
+      filters: [...],
+      onFilter: (value, row) => row.status === value,
+    },
+  ]}
+/>
+```
+
+### 空状态 / 原生属性
+
+empty 自定义空态;className / style / id / data-* / aria-* 透传到表格外层容器;pagination={false} 显式关闭分页。
+
+```tsx
+<Table
+  id="member-empty-table"
+  className="demo-member-table"
+  style={{ boxShadow: "var(--neu-in-sm)" }}
+  data-demo-table="empty"
+  aria-label="成员空表格"
+  rowKey={(row) => `member-${row.id}`}
+  data={[]}
+  empty={<Tag tone="neutral">没有匹配结果</Tag>}
+  pagination={false}
+/>
+```
+
 ## API
 
 **Table**
@@ -122,15 +237,23 @@ rowSelection 提供表头全选、半选状态与按行禁用能力。
 | --- | --- | --- | --- |
 | columns \* | `TableColumn[]` | — | 列定义 |
 | data \* | `Row[]` | — | 数据数组 |
-| rowKey | `string | (row) => key` | — | 行键 |
+| rowKey | `keyof Row | (row) => key` | — | 行键;可传字段名或函数 |
 | variant | `"default" | "striped" | "embossed" | "cards"` | `"default"` | 视觉变体 |
-| pagination | `false | PaginationConfig` | — | 分页配置;false 关闭 |
-| scroll | `TableScrollConfig` | — | 滚动配置:{ x?, y? } |
+| hoverable | `boolean` | `true` | 是否开启行 hover 态 |
+| striped | `boolean` | — | 条纹快捷开关,等价于 variant='striped' |
+| sortKey | `string` | — | 当前排序列 key |
+| sortDir | `"asc" | "desc"` | `"asc"` | 当前排序方向 |
+| onSort | `(key) => void` | — | 点击可排序表头时触发 |
 | rowSelection | `RowSelectionConfig` | — | 行选择配置 |
+| selectable | `boolean` | — | 旧版多选开关,优先使用 rowSelection |
+| selected | `(string | number)[]` | — | 旧版受控选中 key |
+| onSelect | `(keys) => void` | — | 旧版选中变化回调 |
 | expandable | `ExpandableConfig` | — | 可展开行配置 |
-| sortKey / sortDir / onSort | `—` | — | 受控排序 |
-| onRowClick | `(row, i) => void` | — | 点击行 |
-| selectable / selected / onSelect | `—` | — | 旧版多选 API,优先使用 rowSelection |
+| pagination | `false | PaginationConfig` | — | 分页配置;false 关闭 |
+| scroll | `TableScrollConfig` | — | 滚动配置 |
+| onRowClick | `(row, index) => void` | — | 点击行 |
+| empty | `ReactNode` | `"暂无数据"` | 空数据占位内容 |
+| className / style / id / data-* / aria-* | `native attrs` | — | 透传到外层 table-wrap 容器 |
 
 
 **TableColumn**
@@ -158,8 +281,19 @@ rowSelection 提供表头全选、半选状态与按行禁用能力。
 | defaultCurrent | `number` | `1` | 非受控初始页 |
 | pageSize | `number` | `10` | 每页条数 |
 | defaultPageSize | `number` | — | 非受控初始每页条数 |
-| total | `number` | — | 数据总量;默认为 data.length |
-| onChange | `(page, pageSize) => void` | — | 切页回调 |
+| total | `number` | — | 数据总量;默认为过滤后的 data.length |
+| onChange | `(page, pageSize) => void` | — | 切页或切换 pageSize 回调 |
+| showQuickJumper | `boolean` | — | 显示跳页输入 |
+| showSizeChanger | `boolean` | — | 显示每页条数下拉选择 |
+| pageSizeOptions | `number[]` | — | 每页条数选项 |
+
+
+**TableScrollConfig**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| x | `number | string` | — | 横向滚动时内部 table 的最小宽度 |
+| y | `number | string` | — | 纵向滚动时表体最大高度,并启用 sticky header |
 
 
 **RowSelectionConfig**
@@ -180,7 +314,7 @@ rowSelection 提供表头全选、半选状态与按行禁用能力。
 | expandedRowKeys | `(string | number)[]` | — | 受控已展开 key |
 | defaultExpandedRowKeys | `(string | number)[]` | — | 非受控初始展开 |
 | onExpand | `(expanded, row) => void` | — | 展开/收起回调 |
-| expandedRowRender | `(row, i) => ReactNode` | — | 展开面板渲染 |
+| expandedRowRender | `(row, index) => ReactNode` | — | 展开面板渲染 |
 | rowExpandable | `(row) => boolean` | — | 该行是否可展开 |
 
 

package/docs/llms/tablepro.md

@@ -25,6 +25,20 @@ import { TablePro } from "@fangxinyan/lumina";
 />
 ```
 
+### 卡片行分页
+
+variant='cards' 与内置 pagination 共用 TablePro 容器背景,分页区不会单独变成另一块底色。
+
+```tsx
+<TablePro
+  variant="cards"
+  rowKey="id"
+  data={rows}
+  pagination={{ pageSize: 4 }}
+  columns={[...]}
+/>
+```
+
 ### 带可展开行
 
 TablePro 直接透传 expandable 到 Table。

package/docs/llms.md

@@ -3,7 +3,7 @@
 > 拟态风格的 React 18 组件库,目标是 Electron 桌面应用。**写给 AI 编程助手**的按需文档 —— 每个组件单独一个 `.md`,避免一次性读取全部。示例源自 playground 的 demo,可直接复制运行。
 
 - **包名**: `@fangxinyan/lumina`
-- **版本**: `0.6.9`
+- **版本**: `0.6.10`
 - **React 最低版本**: 18
 - **环境**: 带打包器的 React 工程(Vite / Next.js / Webpack / Remix / Electron + Vite 等)
 - **零运行时依赖**: 只依赖 `react` / `react-dom` (peer deps)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fangxinyan/lumina",
-  "version": "0.6.9",
+  "version": "0.6.10",
   "description": "Lumina — Neumorphic component library for Electron & React apps",
   "type": "module",
   "main": "./dist/index.cjs",