ensis-ui 0.0.0-stage → 3.0.0

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

@@ -0,0 +1,61 @@
+/**
+ * Feature 运行时宿主：贡献袋 + 生命周期（对标可插拔中间件总线）。
+ *
+ * 贡献点（实例级，多表互不串扰）：
+ * - contextMenu：右键菜单
+ * - toolbar：表头工具条项
+ * - overlay：浮层/旁路 UI 标记（图表容器挂载点等）
+ *
+ * 每个 RsTable 各自 createRsTableFeatureHost()；不要跨实例复用 host。
+ */
+import type { RsContextMenuItem } from '../../../context-menu/src/context-menu-utils';
+import type { RsTableRowData } from '../utils/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/src/features/rs-table-feature-host.js

@@ -0,0 +1,97 @@
+import { setupTableFeatures } from "./table-features.js";
+//#region src/components/table/src/features/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/src/features/table-features.d.ts

@@ -0,0 +1,149 @@
+/**
+ * RsTable 特性插件协议。
+ *
+ * 目标：新能力以 feature 注册，避免继续向 RsTable.vue 堆分支。
+ *
+ * 已迁出 composable 的内置能力（行为真源）：
+ * - virtual → useRsTableVirtual + useRsTableColumnVirtual + useRsTableScrollLayout
+ * - contextMenu → useRsTableContextMenu
+ * - summary → useRsTableSummary
+ * - sort/selection/filter/tree → useRsTableEngine / useRsTableColumns / useRsTableInteraction
+ * - edit → useTableEdit + useRsTableEditActions
+ * - analytics / chart → useRsTableSelectionSource + useRsTableChartBridge（表外）
+ *
+ * Feature.setup 用于生命周期登记与扩展点；重逻辑不在此重复执行。
+ *
+ * 视图分层（世界级演进）：
+ * - Core / Shell / EditLayer = 行为真源
+ * - RsTableColGroup / Header / Body / BodyRow = 纯视图，不持业务状态
+ */
+import type { RsContextMenuItem } from '../../../context-menu/src/context-menu-utils';
+import type { RsTableRowData } from '../utils/table-utils';
+import type { RsTableAnalyticsSnapshot } from '../composables/useRsTableSelectionSource';
+import type { RsTableOverlayContribution, RsTableToolbarItem } from './rs-table-feature-host';
+import { type RsTableChartSeries, type RsTableChartSeriesDef } from '../utils/table-chart-utils';
+/**
+ * 表格特性插件上下文（只读查询 + 订阅 + 有限贡献点）。
+ * Feature 不得直接操作表格 DOM；图表/指标通过 snapshot / subscribe 接入。
+ */
+export interface RsTableFeatureContext<T extends RsTableRowData = RsTableRowData> {
+    /** 当前筛选/排序后的业务行（Engine.viewRows） */
+    getViewRows: () => T[];
+    /** 当前选中行 */
+    getSelectedRows: () => T[];
+    /**
+     * 分析快照：含 sourceRows（选中优先）与 sourceMode。
+     * 柱状图/饼图等应消费 sourceRows，而不是直接绑原始 data。
+     */
+    getAnalyticsSnapshot: () => RsTableAnalyticsSnapshot<T>;
+    /**
+     * 订阅分析快照变化（浅层：view/selected 引用或 sourceMode）。
+     * @returns teardown
+     */
+    subscribeAnalytics: (listener: (snap: RsTableAnalyticsSnapshot<T>) => void) => () => void;
+    /**
+     * 向右键菜单贡献项（setup 时调用）。
+     * - 传入数组：静态追加
+     * - 传入函数：每次打开菜单时动态贡献（可 push 到 items）
+     */
+    contributeContextMenuItems?: (contributor: RsContextMenuItem[] | ((items: RsContextMenuItem[], menuCtx: {
+        row: T | null;
+        selectedRows: T[];
+    }) => void)) => void;
+    /**
+     * 向工具条贡献项（实例级；多表互不共享贡献袋）。
+     */
+    contributeToolbarItems?: (contributor: RsTableToolbarItem[] | ((items: RsTableToolbarItem[]) => void)) => void;
+    /**
+     * 向 overlay 旁路贡献挂载描述（图表壳等，不直接改表格 DOM）。
+     */
+    contributeOverlay?: (contributor: RsTableOverlayContribution[] | ((items: RsTableOverlayContribution[]) => void)) => void;
+}
+/**
+ * 企业级表格特性插件接口。
+ *
+ * @property id 稳定标识，与 props 开关 / 遥测对齐
+ * @property setup 挂载时调用；可返回 teardown
+ */
+export interface RsTableFeature<T extends RsTableRowData = RsTableRowData> {
+    id: string;
+    setup(ctx: RsTableFeatureContext<T>): void | (() => void);
+}
+/**
+ * 内置特性 id（与 RsTable props 开关映射）。
+ * analytics 不进内置 props 开关：由业务通过 ChartBridge / Feature 外挂。
+ */
+export type RsTableBuiltinFeatureId = 'selection' | 'sort' | 'filter' | 'virtual' | 'edit' | 'tree' | 'contextMenu' | 'summary';
+/** 已有独立 composable 承载的内置 id（feature 仅作登记） */
+export declare const RS_TABLE_FEATURE_COMPOSABLE_MAP: Record<RsTableBuiltinFeatureId, string | null>;
+/** 列布局/拖拽非 builtin feature id，但属内核横切能力 */
+export declare const RS_TABLE_COLUMN_SHELL: {
+    readonly layout: "useRsTableColumnLayout";
+    readonly resize: "useRsTableColumnResize";
+};
+/** 表外分析/图表扩展入口（不进 RsTable 内核渲染） */
+export declare const RS_TABLE_ANALYTICS_SHELL: {
+    readonly selectionSource: "useRsTableSelectionSource";
+    readonly chartBridge: "useRsTableChartBridge";
+    readonly chartUtils: "table-chart-utils";
+};
+/**
+ * 按 props 开关解析应启用的内置特性 id 列表。
+ */
+export declare function resolveBuiltinTableFeatures(flags: {
+    selectable?: boolean;
+    sortableColumns?: boolean;
+    filterable?: boolean;
+    virtual?: boolean | 'auto';
+    editable?: boolean;
+    tree?: boolean;
+    contextMenu?: boolean;
+    summary?: boolean;
+}): RsTableBuiltinFeatureId[];
+/**
+ * 依次 setup 特性列表，并返回统一 teardown（逆序 dispose）。
+ */
+export declare function setupTableFeatures<T extends RsTableRowData>(features: RsTableFeature<T>[], ctx: RsTableFeatureContext<T>): () => void;
+/**
+ * 创建已绑定 composable 真源的内置 feature。
+ */
+export declare function createBuiltinTableFeatures<T extends RsTableRowData>(ids: RsTableBuiltinFeatureId[]): RsTableFeature<T>[];
+/**
+ * 创建分析/图表旁路 feature：setup 时订阅 snapshot，交由业务 listener。
+ * 用于把「选中 → 图表」挂到统一生命周期，而不改 RsTable 模板。
+ */
+export declare function createAnalyticsTableFeature<T extends RsTableRowData>(options: {
+    id?: string;
+    onSnapshot: (snap: RsTableAnalyticsSnapshot<T>) => void;
+}): RsTableFeature<T>;
+/**
+ * 创建右键菜单贡献 feature（静态项或动态函数）。
+ */
+export declare function createContextMenuTableFeature<T extends RsTableRowData>(options: {
+    id?: string;
+    items: RsContextMenuItem[] | ((items: RsContextMenuItem[], menuCtx: {
+        row: T | null;
+        selectedRows: T[];
+    }) => void);
+}): RsTableFeature<T>;
+/** 创建工具条贡献 feature */
+export declare function createToolbarTableFeature(options: {
+    id?: string;
+    items: RsTableToolbarItem[] | ((items: RsTableToolbarItem[]) => void);
+}): RsTableFeature;
+/** 创建 overlay 贡献 feature（图表旁路挂载点等） */
+export declare function createOverlayTableFeature(options: {
+    id?: string;
+    items: RsTableOverlayContribution[] | ((items: RsTableOverlayContribution[]) => void);
+}): RsTableFeature;
+/**
+ * 官方图表 Feature：订阅 analytics → 库无关 series，并登记 overlay 挂载点。
+ * 不捆绑 ECharts/Chart.js；业务用 onSeries 映射 option。
+ */
+export declare function createChartSeriesTableFeature<T extends RsTableRowData>(options: {
+    id?: string;
+    seriesDefs: RsTableChartSeriesDef[] | (() => RsTableChartSeriesDef[]);
+    onSeries: (series: RsTableChartSeries[], snap: RsTableAnalyticsSnapshot<T>) => void;
+    /** overlay 登记；默认 key=chart / slot=chart */
+    overlay?: RsTableOverlayContribution;
+}): RsTableFeature<T>;

package/dist/components/table/src/features/table-features.js

@@ -0,0 +1,119 @@
+import { buildTableChartSeriesList } from "../utils/table-chart-utils.js";
+//#region src/components/table/src/features/table-features.ts
+/** 已有独立 composable 承载的内置 id（feature 仅作登记） */
+var RS_TABLE_FEATURE_COMPOSABLE_MAP = {
+	selection: "useRsTableEngine",
+	sort: "useRsTableEngine",
+	filter: "useRsTableEngine",
+	virtual: "useRsTableVirtual+useRsTableColumnVirtual+useRsTableScrollLayout",
+	edit: "useTableEdit+useRsTableEditActions",
+	tree: "useRsTableEngine+useRsTableInteraction",
+	contextMenu: "useRsTableContextMenu",
+	summary: "useRsTableSummary"
+};
+/** 表外分析/图表扩展入口（不进 RsTable 内核渲染） */
+var RS_TABLE_ANALYTICS_SHELL = {
+	selectionSource: "useRsTableSelectionSource",
+	chartBridge: "useRsTableChartBridge",
+	chartUtils: "table-chart-utils"
+};
+/**
+* 按 props 开关解析应启用的内置特性 id 列表。
+*/
+function resolveBuiltinTableFeatures(flags) {
+	const ids = [];
+	if (flags.selectable) ids.push("selection");
+	if (flags.sortableColumns !== false) ids.push("sort");
+	if (flags.filterable) ids.push("filter");
+	if (flags.virtual !== false) ids.push("virtual");
+	if (flags.editable) ids.push("edit");
+	if (flags.tree) ids.push("tree");
+	if (flags.contextMenu !== false) ids.push("contextMenu");
+	if (flags.summary) ids.push("summary");
+	return ids;
+}
+/**
+* 依次 setup 特性列表，并返回统一 teardown（逆序 dispose）。
+*/
+function setupTableFeatures(features, ctx) {
+	const teardowns = [];
+	for (const feature of features) {
+		const dispose = feature.setup(ctx);
+		if (typeof dispose === "function") teardowns.push(dispose);
+	}
+	return () => {
+		for (const dispose of teardowns.reverse()) dispose();
+	};
+}
+/**
+* 创建已绑定 composable 真源的内置 feature。
+*/
+function createBuiltinTableFeatures(ids) {
+	return ids.map((id) => ({
+		id,
+		setup(ctx) {}
+	}));
+}
+/**
+* 创建分析/图表旁路 feature：setup 时订阅 snapshot，交由业务 listener。
+* 用于把「选中 → 图表」挂到统一生命周期，而不改 RsTable 模板。
+*/
+function createAnalyticsTableFeature(options) {
+	return {
+		id: options.id ?? "analytics",
+		setup(ctx) {
+			return ctx.subscribeAnalytics(options.onSnapshot);
+		}
+	};
+}
+/**
+* 创建右键菜单贡献 feature（静态项或动态函数）。
+*/
+function createContextMenuTableFeature(options) {
+	return {
+		id: options.id ?? "contextMenuExtra",
+		setup(ctx) {
+			ctx.contributeContextMenuItems?.(options.items);
+		}
+	};
+}
+/** 创建工具条贡献 feature */
+function createToolbarTableFeature(options) {
+	return {
+		id: options.id ?? "toolbarExtra",
+		setup(ctx) {
+			ctx.contributeToolbarItems?.(options.items);
+		}
+	};
+}
+/** 创建 overlay 贡献 feature（图表旁路挂载点等） */
+function createOverlayTableFeature(options) {
+	return {
+		id: options.id ?? "overlayExtra",
+		setup(ctx) {
+			ctx.contributeOverlay?.(options.items);
+		}
+	};
+}
+/**
+* 官方图表 Feature：订阅 analytics → 库无关 series，并登记 overlay 挂载点。
+* 不捆绑 ECharts/Chart.js；业务用 onSeries 映射 option。
+*/
+function createChartSeriesTableFeature(options) {
+	return {
+		id: options.id ?? "chartSeries",
+		setup(ctx) {
+			ctx.contributeOverlay?.([options.overlay ?? {
+				key: "chart",
+				slot: "chart",
+				meta: { kind: "series" }
+			}]);
+			return ctx.subscribeAnalytics((snap) => {
+				const defs = typeof options.seriesDefs === "function" ? options.seriesDefs() : options.seriesDefs;
+				options.onSeries(buildTableChartSeriesList(snap.sourceRows, defs), snap);
+			});
+		}
+	};
+}
+//#endregion
+export { RS_TABLE_ANALYTICS_SHELL, RS_TABLE_FEATURE_COMPOSABLE_MAP, createAnalyticsTableFeature, createBuiltinTableFeatures, createChartSeriesTableFeature, createContextMenuTableFeature, createOverlayTableFeature, createToolbarTableFeature, resolveBuiltinTableFeatures, setupTableFeatures };

package/dist/components/table/src/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 './utils/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('./features/rs-table-feature-host').RsTableToolbarItem[];
+    /** 实例 Feature 贡献的 overlay 描述 */
+    getOverlayContributions?: () => import('./features/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/src/rs-table-api.js

@@ -0,0 +1,22 @@
+//#region src/components/table/src/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 };