niuma-ui 1.3.8 → 2.0.0

package/dist/components/table/src/composables/useRsTableShellChrome.d.ts

@@ -0,0 +1,126 @@
+/**
+ * RsTable 壳层编排：i18n 文案、a11y 绑定、Grid 键盘、滚动宿主 class。
+ * 从 RsTable.vue 下沉，SFC 只保留接线。
+ */
+import { type ComputedRef, type Ref } from 'vue';
+import type { useTableEdit } from './useTableEdit';
+import type { RsTableColumn, RsTableRowData, RsTableRowEntry } from '../utils/table-utils';
+type TableEditApi = ReturnType<typeof useTableEdit>;
+export interface UseRsTableShellChromeOptions<T extends RsTableRowData> {
+    ariaLabel: () => string | undefined;
+    loading: () => boolean;
+    dataRows: Ref<Array<Extract<RsTableRowEntry<T>, {
+        type: 'row';
+    }>>> | ComputedRef<Array<Extract<RsTableRowEntry<T>, {
+        type: 'row';
+    }>>>;
+    visibleDataColumns: Ref<RsTableColumn<T>[]> | ComputedRef<RsTableColumn<T>[]>;
+    displayColumns: () => RsTableColumn<T>[];
+    tableEdit: TableEditApi;
+    rowKeyFor: (entry: Extract<RsTableRowEntry<T>, {
+        type: 'row';
+    }>) => string;
+    applyRowClickHighlight: (rowKey: string) => void;
+    pageSize: () => number;
+    onTableKeydown: (event: KeyboardEvent) => void;
+    scrollContainerRef?: Ref<HTMLElement | null | undefined>;
+    /** 滚动宿主 class 所需状态 */
+    hostClass: {
+        bordered: () => boolean;
+        columnBordered: () => boolean;
+        rounded: () => boolean;
+        fill: () => boolean;
+        compact: () => boolean;
+        resolvedSize: () => string;
+        virtualScrollEnabled: () => boolean;
+        virtualColumnsEnabled: () => boolean;
+        dataLength: () => number;
+        infinite: () => boolean;
+        resizable: () => boolean;
+        columnLayout: () => string;
+        useFixedColumnLayout: () => boolean;
+        striped: () => boolean;
+        selectable: () => boolean;
+        isRowSelection: () => boolean;
+        detailExpandable: () => boolean;
+        treeMode: () => boolean;
+        rowDraggable: () => boolean;
+        columnDraggable: () => boolean;
+        scrollX: () => number | string | undefined;
+        overflowXEnabled: () => boolean;
+        contextMenuEnabled: () => boolean;
+        showEditGutterColumn: () => boolean;
+    };
+}
+/**
+ * 壳层 chrome：文案 / a11y / 键盘 / 宿主 class。
+ */
+export declare function useRsTableShellChrome<T extends RsTableRowData>(options: UseRsTableShellChromeOptions<T>): {
+    t: import("../../../..").RsTranslateFn;
+    hasData: ComputedRef<boolean>;
+    headerLabels: ComputedRef<{
+        selectAll: string;
+        index: string;
+        rowStatus: string;
+        dragColumn: string;
+        filterColumn: string;
+        filterPlaceholder: string;
+        filterClear: string;
+        filterApply: string;
+    }>;
+    bodyLabels: ComputedRef<{
+        loading: string;
+        empty: string;
+        loadingMore: string;
+        dragRow: string;
+        expandRow: string;
+        collapseRow: string;
+        selectRow: string;
+        rowCommit: string;
+        rowRollback: string;
+        gutterCommit: string;
+    }>;
+    hasColumnSlot: (key: string) => boolean;
+    hasEditSlot: (key: string) => boolean;
+    tableA11y: ComputedRef<{
+        role: "grid";
+        tabindex: number;
+        'aria-rowcount': number;
+        'aria-colcount': number;
+        'aria-label': string;
+    }>;
+    shellBind: ComputedRef<{
+        class?: import("vue").ClassValue;
+        style?: import("vue").StyleValue;
+        role: "region";
+        'aria-label': string;
+        'aria-busy': boolean | undefined;
+    }>;
+    onShellKeydown: (event: KeyboardEvent) => void;
+    scrollHostClass: ComputedRef<{
+        [x: string]: boolean;
+        'rs-table--bordered': boolean;
+        'rs-table--column-bordered': boolean;
+        'rs-table--rounded': boolean;
+        'rs-table--fill': boolean;
+        'rs-table--compact': boolean;
+        'rs-table--virtual': boolean;
+        'rs-table--virtual-cols': boolean;
+        'rs-table--content-visibility': boolean;
+        'rs-table--infinite': boolean;
+        'rs-table--resizable': boolean;
+        'rs-table--col-auto': boolean;
+        'rs-table--col-fixed': boolean;
+        'rs-table--striped': boolean;
+        'rs-table--selectable': boolean;
+        'rs-table--row-select': boolean;
+        'rs-table--expandable': boolean;
+        'rs-table--tree': boolean;
+        'rs-table--draggable': boolean;
+        'rs-table--scroll-x': boolean;
+        'rs-table--overflow-x': boolean;
+        'rs-table--ctx': boolean;
+        'rs-table--edit-gutter': boolean;
+    }>;
+};
+export {};

package/dist/components/table/src/composables/useRsTableShellChrome.js

@@ -0,0 +1,110 @@
+import { useRsI18n } from "../../../../composables/useRsI18n.js";
+import { useRsTableA11y } from "./useRsTableA11y.js";
+import { useRsTableGridKeyboard } from "./useRsTableGridKeyboard.js";
+import { computed, useAttrs, useSlots } from "vue";
+//#region src/components/table/src/composables/useRsTableShellChrome.ts
+/**
+* RsTable 壳层编排：i18n 文案、a11y 绑定、Grid 键盘、滚动宿主 class。
+* 从 RsTable.vue 下沉，SFC 只保留接线。
+*/
+/**
+* 壳层 chrome：文案 / a11y / 键盘 / 宿主 class。
+*/
+function useRsTableShellChrome(options) {
+	const { t } = useRsI18n();
+	const slots = useSlots();
+	const attrs = useAttrs();
+	const hasData = computed(() => options.dataRows.value.length > 0);
+	const headerLabels = computed(() => ({
+		selectAll: t("table.selectAll"),
+		index: t("table.index"),
+		rowStatus: t("table.rowStatus"),
+		dragColumn: t("table.dragColumn"),
+		filterColumn: t("table.filterColumn"),
+		filterPlaceholder: t("table.filterPlaceholder"),
+		filterClear: t("table.filterClear"),
+		filterApply: t("table.filterApply")
+	}));
+	const bodyLabels = computed(() => ({
+		loading: t("table.loading"),
+		empty: t("table.empty"),
+		loadingMore: t("table.loadingMore"),
+		dragRow: t("table.dragRow"),
+		expandRow: t("table.expandRow"),
+		collapseRow: t("table.collapseRow"),
+		selectRow: t("table.selectRow"),
+		rowCommit: t("table.rowCommit"),
+		rowRollback: t("table.rowRollback"),
+		gutterCommit: t("table.gutterCommit")
+	}));
+	function hasColumnSlot(key) {
+		return Boolean(slots[key]);
+	}
+	function hasEditSlot(key) {
+		return Boolean(slots[`edit-${key}`]);
+	}
+	const { shellA11y, tableA11y } = useRsTableA11y({
+		ariaLabel: options.ariaLabel,
+		defaultLabel: () => t("table.a11yLabel"),
+		loading: options.loading,
+		rowCount: () => options.dataRows.value.length,
+		colCount: () => options.visibleDataColumns.value.length
+	});
+	const shellBind = computed(() => ({
+		...shellA11y.value,
+		...attrs
+	}));
+	const { onGridKeydown } = useRsTableGridKeyboard({
+		tableEdit: options.tableEdit,
+		dataRows: () => options.dataRows.value,
+		rowKeyFor: options.rowKeyFor,
+		colKeys: () => options.visibleDataColumns.value.map((c) => c.key),
+		displayColumns: options.displayColumns,
+		applyRowClickHighlight: options.applyRowClickHighlight,
+		pageSize: options.pageSize,
+		scrollContainerRef: options.scrollContainerRef
+	});
+	function onShellKeydown(event) {
+		if (onGridKeydown(event)) return;
+		options.onTableKeydown(event);
+	}
+	const h = options.hostClass;
+	return {
+		t,
+		hasData,
+		headerLabels,
+		bodyLabels,
+		hasColumnSlot,
+		hasEditSlot,
+		tableA11y,
+		shellBind,
+		onShellKeydown,
+		scrollHostClass: computed(() => ({
+			"rs-table--bordered": h.bordered(),
+			"rs-table--column-bordered": h.columnBordered(),
+			"rs-table--rounded": h.rounded(),
+			"rs-table--fill": h.fill(),
+			"rs-table--compact": h.compact(),
+			[`rs-table--${h.resolvedSize()}`]: true,
+			"rs-table--virtual": h.virtualScrollEnabled(),
+			"rs-table--virtual-cols": h.virtualColumnsEnabled(),
+			"rs-table--content-visibility": !h.virtualScrollEnabled() && h.dataLength() >= 30,
+			"rs-table--infinite": h.infinite(),
+			"rs-table--resizable": h.resizable(),
+			"rs-table--col-auto": h.resizable() && h.columnLayout() === "auto",
+			"rs-table--col-fixed": h.useFixedColumnLayout(),
+			"rs-table--striped": h.striped(),
+			"rs-table--selectable": h.selectable(),
+			"rs-table--row-select": h.isRowSelection(),
+			"rs-table--expandable": h.detailExpandable(),
+			"rs-table--tree": h.treeMode(),
+			"rs-table--draggable": h.rowDraggable() || h.columnDraggable(),
+			"rs-table--scroll-x": !!h.scrollX(),
+			"rs-table--overflow-x": h.overflowXEnabled(),
+			"rs-table--ctx": h.contextMenuEnabled(),
+			"rs-table--edit-gutter": h.showEditGutterColumn()
+		}))
+	};
+}
+//#endregion
+export { useRsTableShellChrome };

package/dist/components/table/src/composables/useRsTableSummary.d.ts

@@ -0,0 +1,44 @@
+/**
+ * RsTable 汇总行编排：是否启用、footer 单元格、前缀 colspan。
+ *
+ * 纯聚合算法在 table-summary-utils；本 composable 对接 props / slots / 前缀列状态。
+ */
+import { type ComputedRef } from 'vue';
+import type { RsTableColumn, RsTableRowData } from '../utils/table-utils';
+import { type RsTableColumnSummary, type RsTableSummaryData, type RsTableSummaryMode } from '../utils/table-summary-utils';
+type ColumnWithSummary<T extends RsTableRowData> = RsTableColumn<T> & {
+    summary?: RsTableColumnSummary<T>;
+};
+export interface UseRsTableSummaryOptions<T extends RsTableRowData> {
+    /** 显式开启汇总行 */
+    showSummary: ComputedRef<boolean | undefined> | (() => boolean | undefined);
+    summaryMode: ComputedRef<RsTableSummaryMode> | (() => RsTableSummaryMode);
+    summaryData: ComputedRef<RsTableSummaryData | null | undefined> | (() => RsTableSummaryData | null | undefined);
+    /** 原始列（判断是否配置 summary） */
+    columns: ComputedRef<ColumnWithSummary<T>[]> | (() => ColumnWithSummary<T>[]);
+    /** 展示列（footer 与表体对齐） */
+    displayColumns: ComputedRef<ColumnWithSummary<T>[]> | (() => ColumnWithSummary<T>[]);
+    viewRows: ComputedRef<T[]> | (() => T[]);
+    /** 是否存在 #summary 插槽（有则不渲染内置行） */
+    hasSummarySlot: ComputedRef<boolean> | (() => boolean);
+    treeMode: ComputedRef<boolean> | (() => boolean);
+    detailExpandable: ComputedRef<boolean> | (() => boolean);
+    showRowDragHandle: ComputedRef<boolean> | (() => boolean);
+    showSelectColumn: ComputedRef<boolean> | (() => boolean);
+    showEditGutterOrIndex: ComputedRef<boolean> | (() => boolean);
+    showRowStatusColumn: ComputedRef<boolean> | (() => boolean);
+}
+/**
+ * 汇总 feature 状态。
+ *
+ * @returns enabled / cells / showBuiltinSummaryRow / prefixColspan
+ */
+export declare function useRsTableSummary<T extends RsTableRowData>(options: UseRsTableSummaryOptions<T>): {
+    summaryFeatureEnabled: ComputedRef<boolean>;
+    summaryCells: ComputedRef<import("../..").RsTableSummaryCell[]>;
+    showBuiltinSummaryRow: ComputedRef<boolean>;
+    summaryPrefixColspan: ComputedRef<number>;
+};
+/** 供 feature 注册表识别：summary 已由 useRsTableSummary 承载 */
+export declare const RS_TABLE_SUMMARY_FEATURE_ID: "summary";
+export {};

package/dist/components/table/src/composables/useRsTableSummary.js

@@ -0,0 +1,52 @@
+import { buildTableSummaryCells, hasTableSummaryConfig } from "../utils/table-summary-utils.js";
+import { computed } from "vue";
+//#region src/components/table/src/composables/useRsTableSummary.ts
+/**
+* RsTable 汇总行编排：是否启用、footer 单元格、前缀 colspan。
+*
+* 纯聚合算法在 table-summary-utils；本 composable 对接 props / slots / 前缀列状态。
+*/
+function read(source) {
+	return typeof source === "function" ? source() : source.value;
+}
+/**
+* 汇总 feature 状态。
+*
+* @returns enabled / cells / showBuiltinSummaryRow / prefixColspan
+*/
+function useRsTableSummary(options) {
+	const summaryFeatureEnabled = computed(() => {
+		if (read(options.showSummary)) return true;
+		return hasTableSummaryConfig({
+			columns: read(options.columns),
+			mode: read(options.summaryMode),
+			summaryData: read(options.summaryData)
+		});
+	});
+	return {
+		summaryFeatureEnabled,
+		summaryCells: computed(() => {
+			if (!summaryFeatureEnabled.value) return [];
+			return buildTableSummaryCells({
+				columns: read(options.displayColumns),
+				rows: read(options.viewRows),
+				mode: read(options.summaryMode),
+				summaryData: read(options.summaryData)
+			});
+		}),
+		showBuiltinSummaryRow: computed(() => summaryFeatureEnabled.value && !read(options.hasSummarySlot)),
+		summaryPrefixColspan: computed(() => {
+			let n = 0;
+			if (read(options.showRowDragHandle)) n += 1;
+			if (read(options.detailExpandable)) n += 1;
+			if (read(options.showSelectColumn)) n += 1;
+			if (read(options.showEditGutterOrIndex)) n += 1;
+			if (read(options.showRowStatusColumn)) n += 1;
+			return n;
+		})
+	};
+}
+/** 供 feature 注册表识别：summary 已由 useRsTableSummary 承载 */
+var RS_TABLE_SUMMARY_FEATURE_ID = "summary";
+//#endregion
+export { RS_TABLE_SUMMARY_FEATURE_ID, useRsTableSummary };

package/dist/components/table/src/composables/useRsTableViewProvide.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 将 Core/Shell/Edit 装配结果安装为实例级 ViewContext。
+ *
+ * 从 RsTable.vue 下沉大块 provide 装配，便于壳层只做接线。
+ * 多表：每次调用 provide 到当前实例树，互不串扰。
+ */
+import type { ComputedRef, Ref } from 'vue';
+import type { RsTableColumn, RsTableRowData, RsTableRowDropPosition, RsTableRowEntry, RsTableRowKey, RsTableSelectionType } from '../utils/table-utils';
+import type { RsTableCellEditFocusMode, RsTableCellEditTrigger } from '../utils/table-edit-utils';
+import { type RsTableBodyLabels, type RsTableHeaderLabels, type RsTableViewContext, type RsTableViewStyle } from '../context/rs-table-view-context';
+type RowEntry<T extends RsTableRowData> = Extract<RsTableRowEntry<T>, {
+    type: 'row';
+}>;
+/** ViewContext 安装所需的状态源（getter / Ref 均可） */
+export interface RsTableViewProvideSources<T extends RsTableRowData> {
+    useFixedColumnLayout: Ref<boolean> | ComputedRef<boolean> | (() => boolean);
+    showRowDragHandle: Ref<boolean> | ComputedRef<boolean> | (() => boolean);
+    detailExpandable: Ref<boolean> | ComputedRef<boolean> | (() => boolean);
+    showSelectColumn: Ref<boolean> | ComputedRef<boolean> | (() => boolean);
+    showEditGutterColumn: Ref<boolean> | ComputedRef<boolean> | (() => boolean);
+    showIndexColumn: Ref<boolean> | ComputedRef<boolean> | (() => boolean);
+    showRowStatusColumn: Ref<boolean> | ComputedRef<boolean> | (() => boolean);
+    columnPadLeft: Ref<number> | ComputedRef<number> | (() => number);
+    columnPadRight: Ref<number> | ComputedRef<number> | (() => number);
+    visibleDataColumns: Ref<RsTableColumn<T>[]> | ComputedRef<RsTableColumn<T>[]> | (() => RsTableColumn<T>[]);
+    prefixWidths: {
+        drag: number;
+        expand: number;
+        select: number;
+        status: number;
+    };
+    resolvedGutterWidth: Ref<number> | ComputedRef<number> | (() => number);
+    resolvedIndexWidth: Ref<number> | ComputedRef<number> | (() => number);
+    isRadioSelection: Ref<boolean> | ComputedRef<boolean> | (() => boolean);
+    selectAllState: Ref<'checked' | 'indeterminate' | 'unchecked'> | ComputedRef<'checked' | 'indeterminate' | 'unchecked'> | (() => 'checked' | 'indeterminate' | 'unchecked');
+    columnDraggable: () => boolean;
+    resizable: () => boolean;
+    multiSort: () => boolean;
+    columnFiltersState: Ref<Record<string, string>> | ComputedRef<Record<string, string>> | (() => Record<string, string>);
+    dragColumnKey: Ref<string | null> | (() => string | null);
+    dropColumnKey: Ref<string | null> | (() => string | null);
+    dragLeadHeaderStyle: Ref<RsTableViewStyle> | ComputedRef<RsTableViewStyle> | (() => RsTableViewStyle);
+    expandLeadHeaderStyle: Ref<RsTableViewStyle> | ComputedRef<RsTableViewStyle> | (() => RsTableViewStyle);
+    selectLeadHeaderStyle: Ref<RsTableViewStyle> | ComputedRef<RsTableViewStyle> | (() => RsTableViewStyle);
+    gutterLeadHeaderStyle: Ref<RsTableViewStyle> | ComputedRef<RsTableViewStyle> | (() => RsTableViewStyle);
+    indexLeadHeaderStyle: Ref<RsTableViewStyle> | ComputedRef<RsTableViewStyle> | (() => RsTableViewStyle);
+    columnHeaderStyleMap: Ref<Map<string, Record<string, string> | undefined>> | ComputedRef<Map<string, Record<string, string> | undefined>> | (() => Map<string, Record<string, string> | undefined>);
+    headerLabels: Ref<RsTableHeaderLabels> | ComputedRef<RsTableHeaderLabels> | (() => RsTableHeaderLabels);
+    loading: () => boolean;
+    hasData: Ref<boolean> | ComputedRef<boolean> | (() => boolean);
+    loadingMore: () => boolean;
+    infinite: () => boolean;
+    bodyColspan: Ref<number> | ComputedRef<number> | (() => number);
+    emptyContentStyle: Ref<RsTableViewStyle> | ComputedRef<RsTableViewStyle> | (() => RsTableViewStyle);
+    virtualScrollEnabled: Ref<boolean> | ComputedRef<boolean> | (() => boolean);
+    virtualSlice: Ref<{
+        paddingTop: number;
+        paddingBottom: number;
+    }> | ComputedRef<{
+        paddingTop: number;
+        paddingBottom: number;
+    }> | (() => {
+        paddingTop: number;
+        paddingBottom: number;
+    });
+    visibleEntries: Ref<RsTableRowEntry<T>[]> | ComputedRef<RsTableRowEntry<T>[]> | (() => RsTableRowEntry<T>[]);
+    rowKey: () => RsTableRowKey<T> | undefined;
+    treeMode: Ref<boolean> | ComputedRef<boolean> | (() => boolean);
+    treeIndentPx: Ref<number> | ComputedRef<number> | (() => number);
+    treeExpandColumnKey: Ref<string | null> | ComputedRef<string | null> | (() => string | null);
+    treeLoadingKeySet: Ref<Set<string>> | ComputedRef<Set<string>> | (() => Set<string>);
+    striped: () => boolean;
+    selectionType: () => RsTableSelectionType;
+    editable: () => boolean;
+    editTrigger: () => RsTableCellEditTrigger;
+    rowCommit: () => boolean;
+    allowNull: () => boolean;
+    editFocusMode: () => RsTableCellEditFocusMode;
+    nullLabel: () => string;
+    dragLeadStyle: Ref<Record<string, string>> | ComputedRef<Record<string, string>> | (() => Record<string, string>);
+    expandLeadStyle: Ref<Record<string, string>> | ComputedRef<Record<string, string>> | (() => Record<string, string>);
+    selectLeadStyle: Ref<Record<string, string>> | ComputedRef<Record<string, string>> | (() => Record<string, string>);
+    indexLeadStyle: Ref<Record<string, string>> | ComputedRef<Record<string, string>> | (() => Record<string, string>);
+    gutterLeadStyle: Ref<Record<string, string>> | ComputedRef<Record<string, string>> | (() => Record<string, string>);
+    columnTdClassMap: Ref<Map<string, string[]>> | ComputedRef<Map<string, string[]>> | (() => Map<string, string[]>);
+    columnStyleMap: Ref<Map<string, Record<string, string> | undefined>> | ComputedRef<Map<string, Record<string, string> | undefined>> | (() => Map<string, Record<string, string> | undefined>);
+    dragRowKeys: Ref<string[]> | (() => string[]);
+    dropRowTargetKey: Ref<string | null> | (() => string | null);
+    dropRowPosition: Ref<RsTableRowDropPosition | null> | (() => RsTableRowDropPosition | null);
+    activeEditCellKey: Ref<string> | ComputedRef<string> | (() => string);
+    activeFocusCellKey: Ref<string> | ComputedRef<string> | (() => string);
+    activeErrorMapSize: Ref<number> | ComputedRef<number> | (() => number);
+    activeValidatingMapSize: Ref<number> | ComputedRef<number> | (() => number);
+    stagedMapSize: () => number;
+    editingDraft: () => string;
+    editingCell: () => {
+        rowKey: string;
+        colKey: string;
+    } | null;
+    focusCell: () => {
+        rowKey: string;
+        colKey: string;
+    } | null;
+    bodyLabels: Ref<RsTableBodyLabels> | ComputedRef<RsTableBodyLabels> | (() => RsTableBodyLabels);
+}
+export type RsTableViewProvideHandlers<T extends RsTableRowData> = Pick<RsTableViewContext<T>, 'resolvedDataColumnWidth' | 'columnFilterValue' | 'sortOrderFor' | 'sortPriorityFor' | 'sortIconName' | 'onToggleSelectAll' | 'onColumnDragOver' | 'onColumnDrop' | 'onColumnDragStart' | 'onColumnDragEnd' | 'updateColumnFilter' | 'onHeaderClick' | 'onResizeStart' | 'onHeaderPointerOver' | 'onHeaderPointerOut' | 'rowKeyFor' | 'isRowSelected' | 'isRowIndeterminate' | 'isRowExpanded' | 'isHighlighted' | 'rowEditPending' | 'isExternalRowPending' | 'treeDepthOf' | 'canExpandRow' | 'canSelectRow' | 'isRowDragByRow' | 'isRowDragging' | 'isRowDropTarget' | 'isRowDirty' | 'hasColumnSlot' | 'hasEditSlot' | 'cellTooltipEnabled' | 'cellTooltipMode' | 'cellTooltipText' | 'cellTooltipFallbackTitle' | 'getCellDraft' | 'isCellDirty' | 'getCellError' | 'isCellValidating' | 'onBodyPointerOver' | 'onBodyPointerOut' | 'onRowClick' | 'onRowSelectMouseDown' | 'onCellClick' | 'onCellDblclick' | 'onCellContextmenu' | 'onRowDblclick' | 'onRowContextmenu' | 'onRowDragOver' | 'onRowDragLeave' | 'onRowDrop' | 'onRowDragStart' | 'onRowDragEnd' | 'onToggleExpand' | 'onToggleSelect' | 'onCellStartEdit' | 'onCellCommit' | 'onCellCancel' | 'onCellUpdateDraft' | 'onCellNavigate' | 'onRowCommit' | 'onRowRollback' | 'onGutterCommit'>;
+/**
+ * 装配并 provide ViewContext；返回 ctx（便于测试读 instanceId）。
+ */
+export declare function useRsTableViewProvide<T extends RsTableRowData>(sources: RsTableViewProvideSources<T>, handlers: RsTableViewProvideHandlers<T>): RsTableViewContext<T>;
+export type { RowEntry };

package/dist/components/table/src/composables/useRsTableViewProvide.js

@@ -0,0 +1,93 @@
+import { isColumnFilterActive } from "../utils/table-utils.js";
+import { createRsTableViewContext, provideRsTableView } from "../context/rs-table-view-context.js";
+//#region src/components/table/src/composables/useRsTableViewProvide.ts
+function val(source) {
+	if (typeof source === "function") return source;
+	return () => source.value;
+}
+/**
+* 装配并 provide ViewContext；返回 ctx（便于测试读 instanceId）。
+*/
+function useRsTableViewProvide(sources, handlers) {
+	const ctx = createRsTableViewContext({
+		state: {
+			useFixedColumnLayout: val(sources.useFixedColumnLayout),
+			showRowDragHandle: val(sources.showRowDragHandle),
+			detailExpandable: val(sources.detailExpandable),
+			showSelectColumn: val(sources.showSelectColumn),
+			showEditGutterColumn: val(sources.showEditGutterColumn),
+			showIndexColumn: val(sources.showIndexColumn),
+			showRowStatusColumn: val(sources.showRowStatusColumn),
+			columnPadLeft: val(sources.columnPadLeft),
+			columnPadRight: val(sources.columnPadRight),
+			visibleDataColumns: val(sources.visibleDataColumns),
+			prefixWidths: () => sources.prefixWidths,
+			resolvedGutterWidth: val(sources.resolvedGutterWidth),
+			resolvedIndexWidth: val(sources.resolvedIndexWidth),
+			isRadioSelection: val(sources.isRadioSelection),
+			selectAllState: val(sources.selectAllState),
+			columnDraggable: sources.columnDraggable,
+			resizable: sources.resizable,
+			multiSort: sources.multiSort,
+			columnFiltersState: val(sources.columnFiltersState),
+			dragColumnKey: val(sources.dragColumnKey),
+			dropColumnKey: val(sources.dropColumnKey),
+			dragLeadHeaderStyle: val(sources.dragLeadHeaderStyle),
+			expandLeadHeaderStyle: val(sources.expandLeadHeaderStyle),
+			selectLeadHeaderStyle: val(sources.selectLeadHeaderStyle),
+			gutterLeadHeaderStyle: val(sources.gutterLeadHeaderStyle),
+			indexLeadHeaderStyle: val(sources.indexLeadHeaderStyle),
+			columnHeaderStyleMap: val(sources.columnHeaderStyleMap),
+			headerLabels: val(sources.headerLabels),
+			loading: sources.loading,
+			hasData: val(sources.hasData),
+			loadingMore: sources.loadingMore,
+			infinite: sources.infinite,
+			bodyColspan: val(sources.bodyColspan),
+			emptyContentStyle: val(sources.emptyContentStyle),
+			virtualScrollEnabled: val(sources.virtualScrollEnabled),
+			virtualSlice: val(sources.virtualSlice),
+			visibleEntries: val(sources.visibleEntries),
+			rowKey: sources.rowKey,
+			treeMode: val(sources.treeMode),
+			treeIndentPx: val(sources.treeIndentPx),
+			treeExpandColumnKey: val(sources.treeExpandColumnKey),
+			treeLoadingKeySet: val(sources.treeLoadingKeySet),
+			striped: sources.striped,
+			selectionType: sources.selectionType,
+			editable: sources.editable,
+			editTrigger: sources.editTrigger,
+			rowCommit: sources.rowCommit,
+			allowNull: sources.allowNull,
+			editFocusMode: sources.editFocusMode,
+			nullLabel: sources.nullLabel,
+			dragLeadStyle: val(sources.dragLeadStyle),
+			expandLeadStyle: val(sources.expandLeadStyle),
+			selectLeadStyle: val(sources.selectLeadStyle),
+			indexLeadStyle: val(sources.indexLeadStyle),
+			gutterLeadStyle: val(sources.gutterLeadStyle),
+			columnTdClassMap: val(sources.columnTdClassMap),
+			columnStyleMap: val(sources.columnStyleMap),
+			dragRowKeys: val(sources.dragRowKeys),
+			dropRowTargetKey: val(sources.dropRowTargetKey),
+			dropRowPosition: val(sources.dropRowPosition),
+			activeEditCellKey: val(sources.activeEditCellKey),
+			activeFocusCellKey: val(sources.activeFocusCellKey),
+			activeErrorMapSize: val(sources.activeErrorMapSize),
+			activeValidatingMapSize: val(sources.activeValidatingMapSize),
+			stagedMapSize: sources.stagedMapSize,
+			editingDraft: sources.editingDraft,
+			editingCell: sources.editingCell,
+			focusCell: sources.focusCell,
+			bodyLabels: val(sources.bodyLabels)
+		},
+		handlers: {
+			...handlers,
+			isColumnFilterActive
+		}
+	});
+	provideRsTableView(ctx);
+	return ctx;
+}
+//#endregion
+export { useRsTableViewProvide };

package/dist/components/table/src/composables/useRsTableVirtual.d.ts

@@ -0,0 +1,75 @@
+/**
+ * RsTable 行虚拟滚动：启用判定、高度前缀和、可视窗口切片。
+ *
+ * 横向列虚拟见 useRsTableColumnVirtual；滚动/视口见 useRsTableScrollLayout。
+ * 本 composable 只消费已算好的 `tableEntries`，不参与 entries 构建，避免循环依赖。
+ */
+import { type ComputedRef, type Ref } from 'vue';
+import { type RsTableRowData, type RsTableRowEntry, type RsTableRowKey } from '../utils/table-utils';
+/**
+ * useRsTableVirtual 入参。
+ * `tableEntriesForThreshold` 用于 auto 阈值，不可直接依赖完整 tableEntries（会循环）。
+ */
+export interface UseRsTableVirtualOptions<T extends RsTableRowData> {
+    /** 根数据行数（非树表阈值用） */
+    dataLength: ComputedRef<number> | (() => number);
+    treeMode: ComputedRef<boolean> | (() => boolean);
+    /** 树表当前展开态下的可见条目粗算 */
+    tableEntriesForThreshold: ComputedRef<number> | (() => number);
+    /** virtual prop：true 强制开 / false 强制关 / undefined 走 auto */
+    virtual: ComputedRef<boolean | undefined> | (() => boolean | undefined);
+    /** auto 模式下的行数阈值 */
+    virtualAutoThreshold: ComputedRef<number> | (() => number);
+    /** fill 为 true 时才允许 auto 开启虚拟（需确定视口高度） */
+    fill: ComputedRef<boolean> | (() => boolean);
+    infinite: ComputedRef<boolean> | (() => boolean);
+    /** infinite 时默认开启虚拟；可显式关掉 */
+    virtualOnInfinite: ComputedRef<boolean> | (() => boolean);
+    overscan: ComputedRef<number> | (() => number);
+    expandRowHeight: ComputedRef<number | undefined> | (() => number | undefined);
+    scrollTop: Ref<number>;
+    viewportHeight: ComputedRef<number> | (() => number);
+    fixedRowHeight: ComputedRef<number> | (() => number);
+    /** 完整 entry 列表（含 group / expand 伪行） */
+    tableEntries: ComputedRef<RsTableRowEntry<T>[]> | (() => RsTableRowEntry<T>[]);
+}
+/**
+ * 树表展开态下的可见行粗算，供 virtual 自动阈值使用。
+ * 仅统计当前 expandedKeys 下可见节点，不做完整 entry 构建。
+ *
+ * @param rows 根节点列表
+ * @param expandedKeys 已展开行 key 集合
+ * @param options 树字段与 rowKey 约定
+ * @returns 可见行数量（含未展开的叶子占位行本身）
+ */
+export declare function flattenVisibleCountRough<R extends RsTableRowData>(rows: readonly R[], expandedKeys: ReadonlySet<string>, options: {
+    childrenField: string;
+    isLeafField: string;
+    lazy: boolean;
+    rowKey?: RsTableRowKey<R>;
+}): number;
+/**
+ * 行虚拟滚动状态。
+ *
+ * @returns
+ * - `virtualScrollEnabled`：是否启用行虚拟
+ * - `virtualHeightModel`：前缀高度模型（总高 / 定位）
+ * - `virtualSlice`：当前窗口 entries + 上下 pad
+ * - `visibleEntries`：切片后的 entries（模板渲染用）
+ */
+export declare function useRsTableVirtual<T extends RsTableRowData>(options: UseRsTableVirtualOptions<T>): {
+    virtualScrollEnabled: ComputedRef<boolean>;
+    virtualHeightModel: ComputedRef<{
+        entries: readonly RsTableRowEntry<T>[];
+        prefix: number[];
+        total: number;
+    }>;
+    virtualSlice: ComputedRef<{
+        entries: RsTableRowEntry<T>[];
+        paddingTop: number;
+        paddingBottom: number;
+    }>;
+    visibleEntries: ComputedRef<RsTableRowEntry<T>[]>;
+};
+/** useRsTableVirtual 返回值类型 */
+export type RsTableVirtualApi<T extends RsTableRowData> = ReturnType<typeof useRsTableVirtual<T>>;