niuma-ui 1.1.12 → 1.2.0

package/dist/components/table/RsTableSummaryRow.impl.js

@@ -0,0 +1,57 @@
+import { Fragment, createCommentVNode, createElementBlock, defineComponent, normalizeClass, normalizeStyle, openBlock, renderList, toDisplayString } from "vue";
+//#region src/components/table/RsTableSummaryRow.vue?vue&type=script&setup=true&lang.ts
+var _hoisted_1 = { class: "rs-table__summary-row" };
+var _hoisted_2 = ["colspan"];
+var _hoisted_3 = ["data-col-key"];
+var RsTableSummaryRow_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineComponent({
+	__name: "RsTableSummaryRow",
+	props: {
+		columns: {},
+		cells: {},
+		prefixColspan: {},
+		padLeft: {},
+		padRight: {}
+	},
+	setup(__props) {
+		/**
+		* 表格 footer 汇总行：按列渲染 summaryCells.text。
+		*
+		* 前缀列（拖拽/展开/选择/序号等）用 colspan 占位，与表体列对齐；
+		* padLeft / padRight 对齐列虚拟滚动的左右垫片。
+		*/
+		return (_ctx, _cache) => {
+			return openBlock(), createElementBlock("tr", _hoisted_1, [
+				(__props.prefixColspan ?? 0) > 0 ? (openBlock(), createElementBlock("td", {
+					key: 0,
+					class: "rs-table__summary-cell rs-table__summary-cell--prefix",
+					colspan: __props.prefixColspan
+				}, null, 8, _hoisted_2)) : createCommentVNode("", true),
+				(__props.padLeft ?? 0) > 0 ? (openBlock(), createElementBlock("td", {
+					key: 1,
+					class: "rs-table__summary-cell rs-table__summary-cell--pad",
+					style: normalizeStyle({
+						width: `${__props.padLeft}px`,
+						minWidth: `${__props.padLeft}px`
+					})
+				}, null, 4)) : createCommentVNode("", true),
+				(openBlock(true), createElementBlock(Fragment, null, renderList(__props.columns, (column) => {
+					return openBlock(), createElementBlock("td", {
+						key: column.key,
+						class: normalizeClass(["rs-table__summary-cell", column.align ? `rs-table__summary-cell--${column.align}` : void 0]),
+						"data-col-key": column.key
+					}, toDisplayString(__props.cells.find((c) => c.key === column.key)?.text ?? ""), 11, _hoisted_3);
+				}), 128)),
+				(__props.padRight ?? 0) > 0 ? (openBlock(), createElementBlock("td", {
+					key: 2,
+					class: "rs-table__summary-cell rs-table__summary-cell--pad",
+					style: normalizeStyle({
+						width: `${__props.padRight}px`,
+						minWidth: `${__props.padRight}px`
+					})
+				}, null, 4)) : createCommentVNode("", true)
+			]);
+		};
+	}
+});
+//#endregion
+export { RsTableSummaryRow_vue_vue_type_script_setup_true_lang_default as default };

package/dist/components/table/RsTableSummaryRow.js

@@ -0,0 +1,5 @@
+import RsTableSummaryRow_vue_vue_type_script_setup_true_lang_default from "./RsTableSummaryRow.impl.js";
+//#region src/components/table/RsTableSummaryRow.vue
+var RsTableSummaryRow_default = RsTableSummaryRow_vue_vue_type_script_setup_true_lang_default;
+//#endregion
+export { RsTableSummaryRow_default as default };

package/dist/components/table/rs-table-api.d.ts

@@ -0,0 +1,65 @@
+/**
+ * RsTable 公开 API 契约（对标 AG Grid GridApi / TanStack table 实例）。
+ *
+ * 设计原则（大厂共性）：
+ * - 业务与第三方只依赖本接口，不依赖 SFC 内部变量
+ * - 加性演进：新增方法用可选字段或 bump RS_TABLE_API_VERSION
+ * - 查询与命令分离：getXxx 无副作用；setXxx / commitXxx 为命令
+ *
+ * 兼容承诺：同主版本内不删除、不改语义已有方法签名。
+ */
+import type { RsTableStagedCell } from '../../composables/useTableEdit';
+import type { RsTableAnalyticsSnapshot } from '../../composables/useRsTableSelectionSource';
+import type { RsTableColumn, RsTableRowData } from '../table-utils';
+/** 公开 API 语义版本（与 package 版本解耦，专指 TableApi 契约） */
+export declare const RS_TABLE_API_VERSION: "1.0.0";
+/**
+ * 表格实例 API：ref / expose / provide / inject 共用同一形状。
+ */
+export interface RsTableApi<T extends RsTableRowData = RsTableRowData> {
+    readonly apiVersion: typeof RS_TABLE_API_VERSION;
+    getRowByKey: (rowKey: string) => T | undefined;
+    getRowByIndex: (index: number) => T | undefined;
+    getColumnValues: (colKey: string) => unknown[];
+    getCellValue: (rowKey: string, colKey: string) => unknown;
+    /** 筛选/排序后的业务行（不含 group/expand 伪行） */
+    getViewRows: () => T[];
+    getSelectedRows: () => T[];
+    getSelectedRowKeys: () => string[];
+    getAnalyticsSnapshot: () => RsTableAnalyticsSnapshot<T>;
+    subscribeAnalytics: (listener: (snap: RsTableAnalyticsSnapshot<T>) => void) => () => void;
+    getHighlightedRowKey: () => string | undefined;
+    setHighlightedRowKey: (key: string | undefined) => void;
+    cancelCellEdit: () => void;
+    cancelAllEdits: () => void;
+    getDirtyCellKeys: () => string[];
+    getCellError: (rowKey: string, colKey: string) => string | undefined;
+    setCellError: (rowKey: string, colKey: string, message: string | null) => void;
+    stageCell: (cell: RsTableStagedCell) => void;
+    rejectRowEdit: (rowKey: string, reason?: string) => void;
+    undoEdit: () => void;
+    redoEdit: () => void;
+    commitRowEdits: (rowKey: string) => void;
+    rollbackRowEdits: (rowKey: string) => void;
+    getActiveFeatureIds?: () => string[];
+    /** 实例 Feature 贡献的工具条项 */
+    getToolbarItems?: () => import('./rs-table-feature-host').RsTableToolbarItem[];
+    /** 实例 Feature 贡献的 overlay 描述 */
+    getOverlayContributions?: () => import('./rs-table-feature-host').RsTableOverlayContribution[];
+}
+/** provide/inject 键：子组件或插槽内拿表格 API */
+export declare const RS_TABLE_API_KEY: unique symbol;
+/**
+ * 由 RsTable 内部装配公开 API（单一出口，避免 expose 与 inject 漂移）。
+ */
+export declare function createRsTableApi<T extends RsTableRowData>(impl: Omit<RsTableApi<T>, 'apiVersion'> & {
+    apiVersion?: typeof RS_TABLE_API_VERSION;
+}): RsTableApi<T>;
+/** 类型守卫：判断未知对象是否像 RsTableApi */
+export declare function isRsTableApi<T extends RsTableRowData = RsTableRowData>(value: unknown): value is RsTableApi<T>;
+/** 列定义辅助：标记某列参与图表分类（文档/约定，不强制运行时） */
+export type RsTableColumnChartMeta = {
+    chartCategory?: boolean;
+    chartValue?: boolean;
+};
+export type RsTableColumnWithChartMeta<T extends RsTableRowData = RsTableRowData> = RsTableColumn<T> & RsTableColumnChartMeta;

package/dist/components/table/rs-table-api.js

@@ -0,0 +1,22 @@
+//#region src/components/table/rs-table-api.ts
+/** 公开 API 语义版本（与 package 版本解耦，专指 TableApi 契约） */
+var RS_TABLE_API_VERSION = "1.0.0";
+/** provide/inject 键：子组件或插槽内拿表格 API */
+var RS_TABLE_API_KEY = Symbol("rsTableApi");
+/**
+* 由 RsTable 内部装配公开 API（单一出口，避免 expose 与 inject 漂移）。
+*/
+function createRsTableApi(impl) {
+	return {
+		apiVersion: impl.apiVersion ?? "1.0.0",
+		...impl
+	};
+}
+/** 类型守卫：判断未知对象是否像 RsTableApi */
+function isRsTableApi(value) {
+	if (!value || typeof value !== "object") return false;
+	const api = value;
+	return typeof api.getViewRows === "function" && typeof api.getSelectedRows === "function" && typeof api.getAnalyticsSnapshot === "function";
+}
+//#endregion
+export { RS_TABLE_API_KEY, RS_TABLE_API_VERSION, createRsTableApi, isRsTableApi };

package/dist/components/table/rs-table-compat-matrix.d.ts

@@ -0,0 +1,24 @@
+/**
+ * RsTable 公开契约兼容矩阵（单一真源）。
+ *
+ * - 测试锁定这些键：删除/改名 = 失败，须 bump RS_TABLE_API_VERSION
+ * - 文档与 CI 共用，避免矩阵与实现漂移
+ */
+/** 当前锁定的 API 契约版本（与 createRsTableApi 一致） */
+export declare const RS_TABLE_COMPAT_API_VERSION: "1.0.0";
+/**
+ * 1.0.x 必选 Api 方法（加性可选方法不在此列）。
+ * 删减任一项视为 breaking。
+ */
+export declare const RS_TABLE_API_REQUIRED_METHODS: readonly ["getRowByKey", "getRowByIndex", "getColumnValues", "getCellValue", "getViewRows", "getSelectedRows", "getSelectedRowKeys", "getAnalyticsSnapshot", "subscribeAnalytics", "getHighlightedRowKey", "setHighlightedRowKey", "cancelCellEdit", "cancelAllEdits", "getDirtyCellKeys", "getCellError", "setCellError", "stageCell", "rejectRowEdit", "undoEdit", "redoEdit", "commitRowEdits", "rollbackRowEdits"];
+/** 1.0.x 加性可选 Api（可缺省，但若存在须为函数） */
+export declare const RS_TABLE_API_OPTIONAL_METHODS: readonly ["getActiveFeatureIds", "getToolbarItems", "getOverlayContributions"];
+/**
+ * 稳定 emit 名（同主版本不删）。
+ * 新增 emit 可追加到测试期望的超集校验。
+ */
+export declare const RS_TABLE_STABLE_EMITS: readonly ["rowClick", "rowDblclick", "cellView", "update:selectedRowKeys", "selectionChange", "loadMore", "cellEditCommit", "cellEditCancel", "rowEditCommit", "rowEditRollback"];
+/** 带默认值的 props 键（与 RS_TABLE_PROP_DEFAULTS 同步校验） */
+export declare const RS_TABLE_DEFAULTED_PROP_KEYS: string[];
+export type RsTableApiRequiredMethod = (typeof RS_TABLE_API_REQUIRED_METHODS)[number];
+export type RsTableApiOptionalMethod = (typeof RS_TABLE_API_OPTIONAL_METHODS)[number];

package/dist/components/table/rs-table-compat-matrix.js

@@ -0,0 +1,64 @@
+import { RS_TABLE_API_VERSION } from "./rs-table-api.js";
+import { RS_TABLE_PROP_DEFAULTS } from "./rs-table-props.js";
+//#region src/components/table/rs-table-compat-matrix.ts
+/**
+* RsTable 公开契约兼容矩阵（单一真源）。
+*
+* - 测试锁定这些键：删除/改名 = 失败，须 bump RS_TABLE_API_VERSION
+* - 文档与 CI 共用，避免矩阵与实现漂移
+*/
+/** 当前锁定的 API 契约版本（与 createRsTableApi 一致） */
+var RS_TABLE_COMPAT_API_VERSION = RS_TABLE_API_VERSION;
+/**
+* 1.0.x 必选 Api 方法（加性可选方法不在此列）。
+* 删减任一项视为 breaking。
+*/
+var RS_TABLE_API_REQUIRED_METHODS = [
+	"getRowByKey",
+	"getRowByIndex",
+	"getColumnValues",
+	"getCellValue",
+	"getViewRows",
+	"getSelectedRows",
+	"getSelectedRowKeys",
+	"getAnalyticsSnapshot",
+	"subscribeAnalytics",
+	"getHighlightedRowKey",
+	"setHighlightedRowKey",
+	"cancelCellEdit",
+	"cancelAllEdits",
+	"getDirtyCellKeys",
+	"getCellError",
+	"setCellError",
+	"stageCell",
+	"rejectRowEdit",
+	"undoEdit",
+	"redoEdit",
+	"commitRowEdits",
+	"rollbackRowEdits"
+];
+/** 1.0.x 加性可选 Api（可缺省，但若存在须为函数） */
+var RS_TABLE_API_OPTIONAL_METHODS = [
+	"getActiveFeatureIds",
+	"getToolbarItems",
+	"getOverlayContributions"
+];
+/**
+* 稳定 emit 名（同主版本不删）。
+* 新增 emit 可追加到测试期望的超集校验。
+*/
+var RS_TABLE_STABLE_EMITS = [
+	"rowClick",
+	"rowDblclick",
+	"cellView",
+	"update:selectedRowKeys",
+	"selectionChange",
+	"loadMore",
+	"cellEditCommit",
+	"cellEditCancel",
+	"rowEditCommit",
+	"rowEditRollback"
+];
+Object.keys(RS_TABLE_PROP_DEFAULTS).sort();
+//#endregion
+export { RS_TABLE_API_OPTIONAL_METHODS, RS_TABLE_API_REQUIRED_METHODS, RS_TABLE_COMPAT_API_VERSION, RS_TABLE_STABLE_EMITS };

package/dist/components/table/rs-table-echarts-adapter.d.ts

@@ -0,0 +1,47 @@
+/**
+ * RsTable 系列 → ECharts option 纯映射（不依赖 echarts 包）。
+ *
+ * 业务侧：`import('echarts').then(e => e.init(el).setOption(option))`
+ * 内核保持库无关；本文件只产出普通 JSON 可序列化结构。
+ */
+import type { RsTableChartSeries } from './table-chart-utils';
+/** 最小 ECharts option 面（刻意放宽，避免绑定具体 echarts 类型版本） */
+export type RsTableEChartsOption = {
+    tooltip?: {
+        trigger?: string;
+    };
+    legend?: {
+        data?: string[];
+    };
+    xAxis?: {
+        type?: string;
+        data?: string[];
+    } | Array<{
+        type?: string;
+        data?: string[];
+    }>;
+    yAxis?: {
+        type?: string;
+    } | Array<{
+        type?: string;
+    }>;
+    series: Array<{
+        id?: string;
+        name?: string;
+        type: 'bar' | 'line' | 'pie';
+        data: Array<number | {
+            name: string;
+            value: number;
+        }>;
+    }>;
+};
+export interface MapRsTableSeriesToEChartsOptions {
+    /** 多系列时是否共用类目轴（默认 true；饼图忽略） */
+    sharedCategoryAxis?: boolean;
+    /** tooltip.trigger，默认按首系列推断 */
+    tooltipTrigger?: 'item' | 'axis';
+}
+/**
+ * 将库无关 series 映射为可直接 setOption 的 ECharts option。
+ */
+export declare function mapRsTableSeriesToEChartsOption(seriesList: readonly RsTableChartSeries[], options?: MapRsTableSeriesToEChartsOptions): RsTableEChartsOption;

package/dist/components/table/rs-table-echarts-adapter.js

@@ -0,0 +1,49 @@
+//#region src/components/table/rs-table-echarts-adapter.ts
+function mapKind(kind) {
+	if (kind === "pie") return "pie";
+	if (kind === "line") return "line";
+	return "bar";
+}
+/**
+* 将库无关 series 映射为可直接 setOption 的 ECharts option。
+*/
+function mapRsTableSeriesToEChartsOption(seriesList, options = {}) {
+	if (!seriesList.length) return { series: [] };
+	const allPie = seriesList.every((s) => s.kind === "pie");
+	const tooltipTrigger = options.tooltipTrigger ?? (allPie ? "item" : "axis");
+	if (allPie) return {
+		tooltip: { trigger: tooltipTrigger },
+		legend: { data: seriesList.flatMap((s) => s.categories) },
+		series: seriesList.map((s) => ({
+			id: s.id,
+			name: s.id,
+			type: "pie",
+			data: s.points.map((p) => ({
+				name: p.name,
+				value: p.value
+			}))
+		}))
+	};
+	const shared = options.sharedCategoryAxis !== false;
+	const primary = seriesList[0];
+	return {
+		tooltip: { trigger: tooltipTrigger },
+		legend: { data: seriesList.map((s) => s.id) },
+		xAxis: shared ? {
+			type: "category",
+			data: primary.categories
+		} : seriesList.map((s) => ({
+			type: "category",
+			data: s.categories
+		})),
+		yAxis: { type: "value" },
+		series: seriesList.map((s) => ({
+			id: s.id,
+			name: s.id,
+			type: mapKind(s.kind),
+			data: s.values
+		}))
+	};
+}
+//#endregion
+export { mapRsTableSeriesToEChartsOption };

package/dist/components/table/rs-table-feature-host.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Feature 运行时宿主：贡献袋 + 生命周期（对标可插拔中间件总线）。
+ *
+ * 贡献点（实例级，多表互不串扰）：
+ * - contextMenu：右键菜单
+ * - toolbar：表头工具条项
+ * - overlay：浮层/旁路 UI 标记（图表容器挂载点等）
+ *
+ * 每个 RsTable 各自 createRsTableFeatureHost()；不要跨实例复用 host。
+ */
+import type { RsContextMenuItem } from '../context-menu-utils';
+import type { RsTableRowData } from '../table-utils';
+import type { RsTableAnalyticsSnapshot } from '../../composables/useRsTableSelectionSource';
+import type { RsTableFeature, RsTableFeatureContext } from './table-features';
+/** 动态右键菜单贡献函数 */
+export type RsTableContextMenuContributor<T extends RsTableRowData> = (items: RsContextMenuItem[], ctx: {
+    row: T | null;
+    selectedRows: T[];
+}) => void;
+/** 工具条贡献项 */
+export interface RsTableToolbarItem {
+    key: string;
+    label: string;
+    icon?: string;
+    disabled?: boolean;
+    onClick?: () => void;
+}
+export type RsTableToolbarContributor = (items: RsTableToolbarItem[]) => void;
+/** Overlay 贡献（旁路挂载描述，不直接操作 DOM） */
+export interface RsTableOverlayContribution {
+    key: string;
+    /** 业务自定义渲染/挂载标识 */
+    slot?: string;
+    meta?: Record<string, unknown>;
+}
+export type RsTableOverlayContributor = (items: RsTableOverlayContribution[]) => void;
+/**
+ * 单次 setup 周期内的贡献收集器（实例私有）。
+ */
+export interface RsTableFeatureHost<T extends RsTableRowData = RsTableRowData> {
+    createContext: (base: {
+        getViewRows: () => T[];
+        getSelectedRows: () => T[];
+        getAnalyticsSnapshot: () => RsTableAnalyticsSnapshot<T>;
+        subscribeAnalytics: (listener: (snap: RsTableAnalyticsSnapshot<T>) => void) => () => void;
+    }) => RsTableFeatureContext<T>;
+    setup: (features: RsTableFeature<T>[], ctx: RsTableFeatureContext<T>) => () => void;
+    mergeContextMenuItems: (baseItems: RsContextMenuItem[], menuCtx: {
+        row: T | null;
+        selectedRows: T[];
+    }) => RsContextMenuItem[];
+    /** 合并 toolbar 贡献 */
+    getToolbarItems: () => RsTableToolbarItem[];
+    /** 合并 overlay 贡献 */
+    getOverlayContributions: () => RsTableOverlayContribution[];
+    getActiveFeatureIds: () => string[];
+}
+/**
+ * 创建 Feature 宿主（每个 RsTable 实例一个 —— 多表请各建各的）。
+ */
+export declare function createRsTableFeatureHost<T extends RsTableRowData>(): RsTableFeatureHost<T>;

package/dist/components/table/rs-table-feature-host.js

@@ -0,0 +1,97 @@
+import { setupTableFeatures } from "./table-features.js";
+//#region src/components/table/rs-table-feature-host.ts
+/**
+* 创建 Feature 宿主（每个 RsTable 实例一个 —— 多表请各建各的）。
+*/
+function createRsTableFeatureHost() {
+	let menuContributors = [];
+	let toolbarContributors = [];
+	let overlayContributors = [];
+	let activeIds = [];
+	function createContext(base) {
+		return {
+			getViewRows: base.getViewRows,
+			getSelectedRows: base.getSelectedRows,
+			getAnalyticsSnapshot: base.getAnalyticsSnapshot,
+			subscribeAnalytics: base.subscribeAnalytics,
+			contributeContextMenuItems(contributor) {
+				if (typeof contributor === "function") {
+					menuContributors.push(contributor);
+					return;
+				}
+				const staticItems = contributor;
+				menuContributors.push((items) => {
+					items.push(...staticItems);
+				});
+			},
+			contributeToolbarItems(contributor) {
+				if (typeof contributor === "function") {
+					toolbarContributors.push(contributor);
+					return;
+				}
+				const staticItems = contributor;
+				toolbarContributors.push((items) => {
+					items.push(...staticItems);
+				});
+			},
+			contributeOverlay(contributor) {
+				if (typeof contributor === "function") {
+					overlayContributors.push(contributor);
+					return;
+				}
+				const staticItems = contributor;
+				overlayContributors.push((items) => {
+					items.push(...staticItems);
+				});
+			}
+		};
+	}
+	function setup(features, ctx) {
+		menuContributors = [];
+		toolbarContributors = [];
+		overlayContributors = [];
+		activeIds = features.map((f) => f.id);
+		const dispose = setupTableFeatures(features, ctx);
+		return () => {
+			dispose();
+			menuContributors = [];
+			toolbarContributors = [];
+			overlayContributors = [];
+			activeIds = [];
+		};
+	}
+	function mergeContextMenuItems(baseItems, menuCtx) {
+		const items = [...baseItems];
+		const before = items.length;
+		for (const contribute of menuContributors) contribute(items, menuCtx);
+		if (before > 0 && items.length > before && !items[before]?.separator) items.splice(before, 0, {
+			key: "__ctx-feature-sep",
+			label: "",
+			separator: true
+		});
+		return items;
+	}
+	function getToolbarItems() {
+		const items = [];
+		for (const contribute of toolbarContributors) contribute(items);
+		return items;
+	}
+	function getOverlayContributions() {
+		const items = [];
+		for (const contribute of overlayContributors) contribute(items);
+		return items;
+	}
+	function getActiveFeatureIds() {
+		return [...activeIds];
+	}
+	return {
+		createContext,
+		setup,
+		mergeContextMenuItems,
+		getToolbarItems,
+		getOverlayContributions,
+		getActiveFeatureIds
+	};
+}
+//#endregion
+export { createRsTableFeatureHost };

package/dist/components/table/rs-table-grid-nav.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ARIA Grid 单元格导航（矩形行列模型，不限于可编辑格）。
+ * 对标 Excel / AG Grid 漫游：箭头、Home/End、Ctrl+Home/End、PageUp/PageDown。
+ */
+export type RsTableGridNavDirection = 'left' | 'right' | 'up' | 'down' | 'home' | 'end' | 'first' | 'last' | 'pageUp' | 'pageDown';
+export interface RsTableGridCellRef {
+    rowKey: string;
+    colKey: string;
+    rowIndex: number;
+}
+/**
+ * 在「行列表 × 列 key」矩形上移动焦点。
+ * rows 按视觉顺序；colKeys 为可见数据列顺序。
+ */
+export declare function navigateGridCell(rows: Array<{
+    rowKey: string;
+    rowIndex: number;
+}>, colKeys: string[], current: RsTableGridCellRef | null, direction: RsTableGridNavDirection, pageSize?: number): RsTableGridCellRef | null;
+/**
+ * 将 KeyboardEvent 映射为网格导航方向；无法识别则返回 null。
+ */
+export declare function resolveGridNavDirection(event: KeyboardEvent): RsTableGridNavDirection | null;

package/dist/components/table/rs-table-grid-nav.js

@@ -0,0 +1,80 @@
+//#region src/components/table/rs-table-grid-nav.ts
+/**
+* 在「行列表 × 列 key」矩形上移动焦点。
+* rows 按视觉顺序；colKeys 为可见数据列顺序。
+*/
+function navigateGridCell(rows, colKeys, current, direction, pageSize = 10) {
+	if (!rows.length || !colKeys.length) return null;
+	const seed = current ?? {
+		rowKey: rows[0].rowKey,
+		colKey: colKeys[0],
+		rowIndex: rows[0].rowIndex
+	};
+	let rowPos = rows.findIndex((r) => r.rowKey === seed.rowKey);
+	if (rowPos < 0) rowPos = 0;
+	let colPos = colKeys.indexOf(seed.colKey);
+	if (colPos < 0) colPos = 0;
+	const lastRow = rows.length - 1;
+	const lastCol = colKeys.length - 1;
+	const step = Math.max(1, pageSize);
+	switch (direction) {
+		case "left":
+			colPos = Math.max(0, colPos - 1);
+			break;
+		case "right":
+			colPos = Math.min(lastCol, colPos + 1);
+			break;
+		case "up":
+			rowPos = Math.max(0, rowPos - 1);
+			break;
+		case "down":
+			rowPos = Math.min(lastRow, rowPos + 1);
+			break;
+		case "home":
+			colPos = 0;
+			break;
+		case "end":
+			colPos = lastCol;
+			break;
+		case "first":
+			rowPos = 0;
+			colPos = 0;
+			break;
+		case "last":
+			rowPos = lastRow;
+			colPos = lastCol;
+			break;
+		case "pageUp":
+			rowPos = Math.max(0, rowPos - step);
+			break;
+		case "pageDown":
+			rowPos = Math.min(lastRow, rowPos + step);
+			break;
+		default: break;
+	}
+	const row = rows[rowPos];
+	return {
+		rowKey: row.rowKey,
+		colKey: colKeys[colPos],
+		rowIndex: row.rowIndex
+	};
+}
+/**
+* 将 KeyboardEvent 映射为网格导航方向；无法识别则返回 null。
+*/
+function resolveGridNavDirection(event) {
+	const mod = event.ctrlKey || event.metaKey;
+	switch (event.key) {
+		case "ArrowLeft": return "left";
+		case "ArrowRight": return "right";
+		case "ArrowUp": return "up";
+		case "ArrowDown": return "down";
+		case "Home": return mod ? "first" : "home";
+		case "End": return mod ? "last" : "end";
+		case "PageUp": return "pageUp";
+		case "PageDown": return "pageDown";
+		default: return null;
+	}
+}
+//#endregion
+export { navigateGridCell, resolveGridNavDirection };

package/dist/components/table/rs-table-header-types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * RsTableHeader 视图契约（对标列头渲染层，与 Engine 解耦）。
+ */
+import type { CSSProperties } from 'vue';
+import type { RsTableColumn, RsTableRowData } from '../table-utils';
+export interface RsTableHeaderProps<T extends RsTableRowData = RsTableRowData> {
+    showRowDragHandle: boolean;
+    detailExpandable: boolean;
+    showSelectColumn: boolean;
+    isRadioSelection: boolean;
+    selectAllState: 'checked' | 'indeterminate' | 'unchecked';
+    showEditGutterColumn: boolean;
+    showIndexColumn: boolean;
+    showRowStatusColumn: boolean;
+    columnPadLeft: number;
+    columnPadRight: number;
+    visibleDataColumns: RsTableColumn<T>[];
+    columnDraggable: boolean;
+    resizable: boolean;
+    multiSort: boolean;
+    columnFiltersState: Record<string, string>;
+    dragColumnKey: string | null;
+    dropColumnKey: string | null;
+    dragLeadHeaderStyle: CSSProperties | Record<string, string> | undefined;
+    expandLeadHeaderStyle: CSSProperties | Record<string, string> | undefined;
+    selectLeadHeaderStyle: CSSProperties | Record<string, string> | undefined;
+    gutterLeadHeaderStyle: CSSProperties | Record<string, string> | undefined;
+    indexLeadHeaderStyle: CSSProperties | Record<string, string> | undefined;
+    columnHeaderStyleMap: Map<string, Record<string, string> | undefined>;
+    columnFilterValue: (key: string) => string;
+    isColumnFilterActive: (filters: Record<string, string>, key: string) => boolean;
+    sortOrderFor: (key: string) => string | null | undefined;
+    sortPriorityFor: (key: string) => number;
+    sortIconName: (key: string) => string;
+    labels: {
+        selectAll: string;
+        index: string;
+        rowStatus: string;
+        dragColumn: string;
+        filterColumn: string;
+        filterPlaceholder: string;
+        filterClear: string;
+        filterApply: string;
+    };
+}