@dazhicheng/ui 1.6.7 → 1.6.8

package/dist/components/tt-vtable/src/engine/visactor/createListTable.js

@@ -0,0 +1,63 @@
+import { shallowRef as g } from "vue";
+import { changeVisactorCellValue as C, deleteVisactorRecords as h, updateVisactorRecords as I, addVisactorRecords as P, setVisactorRecords as b } from "./record-adapter.js";
+function x(u) {
+  const a = g();
+  let n = !1;
+  a.value = u;
+  function o() {
+    return n ? void 0 : a.value;
+  }
+  function l(e) {
+    n || (a.value = e);
+  }
+  function r(e) {
+    a.value && b(a.value, e);
+  }
+  function i(e, t) {
+    a.value && P(a.value, e, t);
+  }
+  function c(e, t) {
+    a.value && I(a.value, e, t);
+  }
+  function s(e) {
+    a.value && h(a.value, e);
+  }
+  function d(e, t, m) {
+    return a.value ? C(a.value, e, t, m) : !1;
+  }
+  function f(e) {
+    return a.value ? a.value.updateOption(e) : Promise.resolve();
+  }
+  function v(e) {
+    var t;
+    (t = a.value) == null || t.updateColumns(e);
+  }
+  function p(e) {
+    var t;
+    (t = a.value) == null || t.updatePagination(e);
+  }
+  function R() {
+    var e;
+    (e = a.value) == null || e.renderWithRecreateCells();
+  }
+  function V() {
+    n || (n = !0, a.value = void 0);
+  }
+  return {
+    getInstance: o,
+    setInstance: l,
+    setRecords: r,
+    addRecords: i,
+    updateRecords: c,
+    deleteRecords: s,
+    changeCellValue: d,
+    updateOptions: f,
+    updateColumns: v,
+    updatePagination: p,
+    recalculate: R,
+    release: V
+  };
+}
+export {
+  x as createVisactorTableEngine
+};

package/dist/components/tt-vtable/src/engine/visactor/createVueCellLayout.d.ts

@@ -0,0 +1,37 @@
+import { TYPES } from '@visactor/vtable';
+import { TtVTableApi, TtVTableColumn, TtVTableRendererSlots, TtVTableRowKey } from '../../public';
+/** 创建正文 Vue DOM 布局所需上下文。 */
+export interface CreateVueCellLayoutOptions<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 当前语义列。 */
+    column: TtVTableColumn<Row, Key>;
+    /** 当前稳定公共 API。 */
+    tableApi: TtVTableApi<Row, Key>;
+    /** 当前组件可用的命名插槽。 */
+    rendererSlots: TtVTableRendererSlots<Row, Key>;
+    /** 从记录读取业务主键。 */
+    getRowKey: (record: Row) => Key;
+}
+/** 创建表头 Vue DOM 布局所需上下文。 */
+export interface CreateVueHeaderLayoutOptions<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 当前语义列。 */
+    column: TtVTableColumn<Row, Key>;
+    /** 当前稳定公共 API。 */
+    tableApi: TtVTableApi<Row, Key>;
+    /** 当前组件可用的命名插槽。 */
+    rendererSlots: TtVTableRendererSlots<Row, Key>;
+}
+/** 官方 customLayout 返回值。 */
+type VisactorCustomLayout = TYPES.ICustomLayoutFuc;
+/**
+ * 创建正文 Vue DOM customLayout。
+ * @param options renderer、API、插槽与主键读取配置
+ * @returns 原生 VTable customLayout
+ */
+export declare function createVueCellLayout<Row extends Record<string, unknown>, Key extends TtVTableRowKey>(options: CreateVueCellLayoutOptions<Row, Key>): VisactorCustomLayout;
+/**
+ * 创建表头 Vue DOM headerCustomLayout。
+ * @param options renderer、API 与插槽配置
+ * @returns 原生 VTable headerCustomLayout
+ */
+export declare function createVueHeaderLayout<Row extends Record<string, unknown>, Key extends TtVTableRowKey>(options: CreateVueHeaderLayoutOptions<Row, Key>): VisactorCustomLayout;
+export {};

package/dist/components/tt-vtable/src/engine/visactor/createVueCellLayout.js

@@ -0,0 +1,133 @@
+import { Group as V } from "@visactor/vue-vtable";
+import { createCustomLayout as w } from "@visactor/vue-vtable/es/utils/customLayoutUtils";
+import "axios";
+import "element-plus";
+import { isPromise as S, isObject as R, isFunction as u, isNumber as g, isDef as h } from "../../../../../packages/utils/src/is.js";
+import { defineComponent as $, h as a, Fragment as k } from "vue";
+import "dayjs";
+import "numeral";
+import "xe-utils";
+import "dayjs/plugin/utc";
+import "dayjs/plugin/timezone";
+import "../../../../../node_modules/.pnpm/decimal.js@10.6.0/node_modules/decimal.js/decimal.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/aes.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/enc-utf8.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/mode-ecb.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/pad-pkcs7.js";
+import "lodash-es";
+import { createTtVTableError as p } from "../../public/table-errors.js";
+const I = $({
+  name: "VTableVueRendererHost",
+  props: {
+    renderContent: { type: Function, required: !0 },
+    renderContext: { type: Object, required: !0 }
+  },
+  setup(e) {
+    return () => e.renderContent(e.renderContext);
+  }
+});
+function d(e, t) {
+  return a(I, {
+    renderContent: e,
+    renderContext: t
+  });
+}
+function L(e) {
+  return `${g(e) ? "number" : "string"}:${encodeURIComponent(String(e))}`;
+}
+function b(e, t) {
+  if (!(u(e.render) || e.slot))
+    throw p("TT_VTABLE_RENDERER_INVALID", `列 ${t} 的 Vue renderer 必须配置 render 或 slot。`, {
+      columnKey: t
+    });
+}
+function A(e, t) {
+  return a(k, { key: t }, [e]);
+}
+function f(e, t, r, l, o) {
+  const c = o.table, n = o.rect ?? c.getCellRect(o.col, o.row), m = A(e, t), i = a(V, {
+    width: n.width,
+    height: n.height,
+    clip: !0,
+    pickable: !1,
+    vue: {
+      id: t,
+      element: m,
+      pointerEvents: r
+    }
+  }), { rootComponent: s } = w(i, l, o);
+  return { rootContainer: s, renderDefault: !1, enableCellPadding: !1 };
+}
+function _(e, t, r, l) {
+  if (u(e.render)) return d(e.render, r);
+  const o = e.slot ? t[e.slot] : void 0;
+  if (!u(o))
+    throw p("TT_VTABLE_SLOT_MISSING", `列 ${l} 缺少命名插槽 ${e.slot ?? ""}。`, {
+      columnKey: l,
+      slot: e.slot
+    });
+  return d(o, r);
+}
+function E(e, t, r, l) {
+  if (u(e.render)) return d(e.render, r);
+  const o = e.slot ? t[e.slot] : void 0;
+  if (!u(o))
+    throw p("TT_VTABLE_SLOT_MISSING", `列 ${l} 缺少表头命名插槽 ${e.slot ?? ""}。`, {
+      columnKey: l,
+      slot: e.slot
+    });
+  return d(o, r);
+}
+function Y(e) {
+  const t = e.column.renderer;
+  return b(t, e.column.key), (r) => {
+    const l = r.table, o = l.getCellOriginRecord(r.col, r.row);
+    if (S(o) || !R(o))
+      return f(
+        void 0,
+        `${e.column.key}:pending:${r.col}:${r.row}`,
+        !1,
+        !1,
+        r
+      );
+    const c = o, n = e.getRowKey(c), m = l.getRecordShowIndexByCell(r.col, r.row), i = `${e.column.key}:${L(n)}`, s = {
+      record: c,
+      rowKey: n,
+      rowIndex: m,
+      column: e.column,
+      field: e.column.field,
+      value: r.value,
+      tableApi: e.tableApi,
+      setCellValue: (T) => {
+        h(e.column.field) && e.tableApi.records.setCellValue(n, e.column.field, T, "renderer");
+      },
+      nativeContext: {
+        col: r.col,
+        row: r.row,
+        table: l,
+        rect: r.rect
+      }
+    }, y = _(t, e.rendererSlots, s, e.column.key);
+    return f(y, i, !!t.interactive, !1, r);
+  };
+}
+function Z(e) {
+  const t = e.column.headerRenderer;
+  return b(t, e.column.key), (r) => {
+    const l = r.table, o = `${e.column.key}:header`, c = {
+      column: e.column,
+      tableApi: e.tableApi,
+      nativeContext: {
+        col: r.col,
+        row: r.row,
+        table: l,
+        rect: r.rect
+      }
+    }, n = E(t, e.rendererSlots, c, e.column.key);
+    return f(n, o, !!t.interactive, !0, r);
+  };
+}
+export {
+  Y as createVueCellLayout,
+  Z as createVueHeaderLayout
+};

package/dist/components/tt-vtable/src/engine/visactor/index.d.ts

@@ -0,0 +1,8 @@
+/** TtVTable 内部 VisActor 边界。 */
+export * from './createListTable';
+export * from './createVueCellLayout';
+export * from './native-boundaries';
+export * from './record-adapter';
+export * from './toColumnDefinitions';
+export * from './toListTableOptions';
+export * from './types';

package/dist/components/tt-vtable/src/engine/visactor/native-boundaries.d.ts

@@ -0,0 +1,23 @@
+import { ListTable } from '@visactor/vtable';
+import { TtVTableNativeEvents, TtVTableNativeOptions } from '../../public';
+/** 运行时禁止业务覆盖的原生 options。 */
+export declare const TT_VTABLE_RESERVED_NATIVE_OPTIONS: readonly ["columns", "pagination", "records"];
+/** 运行时禁止业务监听的原生事件。 */
+export declare const TT_VTABLE_RESERVED_NATIVE_EVENTS: readonly ["change_cell_value", "change_cell_values", "checkbox_state_change", "radio_state_change", "tree_hierarchy_state_change"];
+/**
+ * 校验原生 options 没有覆盖封装层受控状态。
+ * @param nativeOptions 业务传入的原生 options
+ */
+export declare function validateNativeOptions(nativeOptions?: TtVTableNativeOptions): void;
+/**
+ * 校验业务没有通过 nativeEvents 订阅 feature 独占事件。
+ * @param nativeEvents 业务传入的原生事件
+ */
+export declare function validateNativeEvents(nativeEvents?: TtVTableNativeEvents): void;
+/**
+ * 绑定允许透传的原生事件，并返回幂等清理函数。
+ * @param table 原生 ListTable
+ * @param nativeEvents 业务原生事件集合
+ * @returns 事件清理函数
+ */
+export declare function bindNativeEvents(table: ListTable, nativeEvents?: TtVTableNativeEvents): () => void;

package/dist/components/tt-vtable/src/engine/visactor/native-boundaries.js

@@ -0,0 +1,70 @@
+import "axios";
+import "element-plus";
+import { isObject as i, isFunction as T } from "../../../../../packages/utils/src/is.js";
+import "vue";
+import "dayjs";
+import "numeral";
+import "xe-utils";
+import "dayjs/plugin/utc";
+import "dayjs/plugin/timezone";
+import "../../../../../node_modules/.pnpm/decimal.js@10.6.0/node_modules/decimal.js/decimal.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/aes.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/enc-utf8.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/mode-ecb.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/pad-pkcs7.js";
+import "lodash-es";
+import { createTtVTableError as n } from "../../public/table-errors.js";
+const _ = ["columns", "pagination", "records"], s = [
+  "change_cell_value",
+  "change_cell_values",
+  "checkbox_state_change",
+  "radio_state_change",
+  "tree_hierarchy_state_change"
+];
+function B(t) {
+  if (!t || !i(t)) return;
+  _.forEach((e) => {
+    if (e in t)
+      throw n("TT_VTABLE_NATIVE_OPTION_RESERVED", `nativeOptions.${e} 由 TtVTable 控制。`, {
+        optionKey: e
+      });
+  });
+  const r = t.customConfig;
+  if (i(r) && "createReactContainer" in r)
+    throw n(
+      "TT_VTABLE_NATIVE_OPTION_RESERVED",
+      "nativeOptions.customConfig.createReactContainer 由 TtVTable 控制。",
+      { optionKey: "customConfig.createReactContainer" }
+    );
+}
+function f(t) {
+  !t || !i(t) || s.forEach((r) => {
+    if (r in t)
+      throw n("TT_VTABLE_NATIVE_EVENT_RESERVED", `nativeEvents.${r} 由 TtVTable 内部处理。`, {
+        eventName: r
+      });
+  });
+}
+function m(t, r, e) {
+  const o = e;
+  return t.on(r, o);
+}
+function D(t, r) {
+  f(r);
+  const e = [];
+  r && Object.keys(r).forEach((a) => {
+    const E = r[a];
+    T(E) && e.push(m(t, a, E));
+  });
+  let o = !1;
+  return () => {
+    o || (o = !0, e.forEach((c) => t.off(c)), e.length = 0);
+  };
+}
+export {
+  s as TT_VTABLE_RESERVED_NATIVE_EVENTS,
+  _ as TT_VTABLE_RESERVED_NATIVE_OPTIONS,
+  D as bindNativeEvents,
+  f as validateNativeEvents,
+  B as validateNativeOptions
+};

package/dist/components/tt-vtable/src/engine/visactor/record-adapter.d.ts

@@ -0,0 +1,38 @@
+import { ListTable } from '@visactor/vtable';
+import { TtVTableFieldPath } from '../../public';
+import { VisactorRecordIndex } from './types';
+/**
+ * 使用原生 setRecords 全量替换工作列表。
+ * @param table 原生 ListTable
+ * @param records 运行时可变工作列表
+ */
+export declare function setVisactorRecords<Row extends Record<string, unknown>>(table: ListTable, records: Row[]): void;
+/**
+ * 使用原生 addRecords 插入记录。
+ * @param table 原生 ListTable
+ * @param records 待插入记录
+ * @param recordIndex 根记录或树节点源索引
+ */
+export declare function addVisactorRecords<Row extends Record<string, unknown>>(table: ListTable, records: Row[], recordIndex?: VisactorRecordIndex): void;
+/**
+ * 使用原生 updateRecords 一次更新多条记录。
+ * @param table 原生 ListTable
+ * @param records 更新后的记录
+ * @param recordIndexes 对应源索引
+ */
+export declare function updateVisactorRecords<Row extends Record<string, unknown>>(table: ListTable, records: Row[], recordIndexes: VisactorRecordIndex[]): void;
+/**
+ * 使用原生 deleteRecords 删除多条记录。
+ * @param table 原生 ListTable
+ * @param recordIndexes 待删除源索引
+ */
+export declare function deleteVisactorRecords(table: ListTable, recordIndexes: VisactorRecordIndex[]): void;
+/**
+ * 使用原生 changeCellValue 刷新一个可见单元格。
+ * @param table 原生 ListTable
+ * @param recordIndex 根记录或树节点源索引
+ * @param field 字段路径
+ * @param value 最新运行时值
+ * @returns 是否命中一个可见单元格
+ */
+export declare function changeVisactorCellValue(table: ListTable, recordIndex: VisactorRecordIndex, field: TtVTableFieldPath, value: unknown): boolean;

package/dist/components/tt-vtable/src/engine/visactor/record-adapter.js

@@ -0,0 +1,41 @@
+import "axios";
+import "element-plus";
+import { isNumber as c, isArray as l } from "../../../../../packages/utils/src/is.js";
+import "vue";
+import "dayjs";
+import "numeral";
+import "xe-utils";
+import "dayjs/plugin/utc";
+import "dayjs/plugin/timezone";
+import "../../../../../node_modules/.pnpm/decimal.js@10.6.0/node_modules/decimal.js/decimal.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/aes.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/enc-utf8.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/mode-ecb.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/pad-pkcs7.js";
+import "lodash-es";
+function y(e, r) {
+  e.setRecords(r);
+}
+function B(e, r, o) {
+  e.addRecords(r, o, !1);
+}
+function F(e, r, o) {
+  e.updateRecords(r, o, !1);
+}
+function I(e, r) {
+  const o = r.filter(c), i = r.filter(l);
+  i.length && e.deleteRecords(i, !1), o.length && e.deleteRecords(o, !1);
+}
+function N(e, r, o, i) {
+  const t = e.getCellAddrByFieldRecord(o, r);
+  if (!t || t.col < 0 || t.row < 0) return !1;
+  const s = i;
+  return e.changeCellValue(t.col, t.row, s, !1, !1, !0), !0;
+}
+export {
+  B as addVisactorRecords,
+  N as changeVisactorCellValue,
+  I as deleteVisactorRecords,
+  y as setVisactorRecords,
+  F as updateVisactorRecords
+};

package/dist/components/tt-vtable/src/engine/visactor/toColumnDefinitions.d.ts

@@ -0,0 +1,45 @@
+import { ColumnDefine } from '@visactor/vtable';
+import { TtVTableApi, TtVTableColumn, TtVTableRendererSlots, TtVTableRowKey } from '../../public';
+/** 列转换所需的稳定运行时依赖。 */
+export interface ToColumnDefinitionsOptions<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 当前稳定公共 API。 */
+    tableApi: TtVTableApi<Row, Key>;
+    /** 当前组件可用的 Vue renderer 插槽。 */
+    rendererSlots: TtVTableRendererSlots<Row, Key>;
+    /** 从记录读取业务主键。 */
+    getRowKey: (record: Row) => Key;
+}
+/**
+ * 按左冻结、普通、右冻结顺序规范顶层列。
+ * @param columns 业务语义列
+ * @returns 保持各分组相对顺序的顶层列
+ */
+export declare function toFrozenColumnOrder<Row extends Record<string, unknown>, Key extends TtVTableRowKey>(columns: readonly TtVTableColumn<Row, Key>[]): TtVTableColumn<Row, Key>[];
+/**
+ * 校验整棵列树的 column.key 唯一且非空。
+ * @param columns 业务语义列
+ */
+export declare function validateColumnKeys<Row extends Record<string, unknown>, Key extends TtVTableRowKey>(columns: readonly TtVTableColumn<Row, Key>[]): void;
+/**
+ * 把语义列树转换为原生 VTable 列。
+ * @param columns 业务语义列
+ * @param options 稳定运行时依赖
+ * @param shouldValidate 是否校验整棵列树
+ * @returns 原生列集合
+ */
+export declare function toColumnDefinitions<Row extends Record<string, unknown>, Key extends TtVTableRowKey>(columns: readonly TtVTableColumn<Row, Key>[], options: ToColumnDefinitionsOptions<Row, Key>, shouldValidate?: boolean): ColumnDefine[];
+/**
+ * 计算当前顶层左、右冻结列数量。
+ * @param columns 已按冻结位置排序的顶层列
+ * @returns 左、右冻结列数量
+ */
+export declare function getFrozenColumnCounts<Row extends Record<string, unknown>, Key extends TtVTableRowKey>(columns: readonly TtVTableColumn<Row, Key>[]): {
+    frozenColCount: number;
+    rightFrozenColCount: number;
+};
+/**
+ * 汇总列级 Vue DOM 缓存建议值。
+ * @param columns 业务语义列
+ * @returns 所有有效列级缓存上限之和
+ */
+export declare function getColumnDomCacheCount<Row extends Record<string, unknown>, Key extends TtVTableRowKey>(columns: readonly TtVTableColumn<Row, Key>[]): number | undefined;

package/dist/components/tt-vtable/src/engine/visactor/toColumnDefinitions.js

@@ -0,0 +1,73 @@
+import { createTtVTableError as C } from "../../public/table-errors.js";
+import { createVueHeaderLayout as d, createVueCellLayout as h } from "./createVueCellLayout.js";
+function y(e) {
+  const r = e.filter((o) => o.frozen === !0 || o.frozen === "left"), t = e.filter((o) => !o.frozen), n = e.filter((o) => o.frozen === "right");
+  return [...r, ...t, ...n];
+}
+function c(e) {
+  const r = /* @__PURE__ */ new Set();
+  function t(n) {
+    n.forEach((o) => {
+      var i;
+      if (!o.key || r.has(o.key))
+        throw C(
+          "TT_VTABLE_DUPLICATE_COLUMN_KEY",
+          `column.key ${o.key || "<empty>"} 无效或重复。`,
+          {
+            columnKey: o.key
+          }
+        );
+      r.add(o.key), (i = o.columns) != null && i.length && t(o.columns);
+    });
+  }
+  t(e);
+}
+function m(e, r) {
+  var a;
+  const t = e.native ?? {}, n = (a = e.columns) != null && a.length ? g(y(e.columns), r, !1) : void 0, o = "customLayout" in t ? t.customLayout : void 0, i = "headerCustomLayout" in t ? t.headerCustomLayout : void 0;
+  return {
+    ...t,
+    key: e.key,
+    field: e.field,
+    title: e.title,
+    width: e.width,
+    minWidth: e.minWidth,
+    maxWidth: e.maxWidth,
+    style: e.align ? { textAlign: e.align, ...t.style ?? {} } : t.style,
+    hide: e.visible === !1,
+    tree: e.tree,
+    columns: n,
+    customLayout: e.renderer ? h({
+      column: e,
+      tableApi: r.tableApi,
+      rendererSlots: r.rendererSlots,
+      getRowKey: r.getRowKey
+    }) : o,
+    headerCustomLayout: e.headerRenderer ? d({ column: e, tableApi: r.tableApi, rendererSlots: r.rendererSlots }) : i
+  };
+}
+function g(e, r, t = !0) {
+  return t && c(e), e.map((n) => m(n, r));
+}
+function z(e) {
+  const r = e.filter((n) => n.frozen === !0 || n.frozen === "left").length, t = e.filter((n) => n.frozen === "right").length;
+  return { frozenColCount: r, rightFrozenColCount: t };
+}
+function b(e) {
+  let r = 0, t = !1;
+  function n(o) {
+    o.forEach((i) => {
+      var u, f, l;
+      const s = (u = i.renderer) == null ? void 0 : u.maxCacheCount, a = (f = i.headerRenderer) == null ? void 0 : f.maxCacheCount;
+      Number.isFinite(s) && s > 0 && (r += Math.floor(s), t = !0), Number.isFinite(a) && a > 0 && (r += Math.floor(a), t = !0), (l = i.columns) != null && l.length && n(i.columns);
+    });
+  }
+  return n(e), t ? r : void 0;
+}
+export {
+  b as getColumnDomCacheCount,
+  z as getFrozenColumnCounts,
+  g as toColumnDefinitions,
+  y as toFrozenColumnOrder,
+  c as validateColumnKeys
+};

package/dist/components/tt-vtable/src/engine/visactor/toListTableOptions.d.ts

@@ -0,0 +1,25 @@
+import { ListTableConstructorOptions } from '@visactor/vtable';
+import { TtVTableApi, TtVTableColumn, TtVTableNativeOptions, TtVTableRendererSlots, TtVTableRenderingOptions, TtVTableRowKey } from '../../public';
+/** 创建 ListTable options 所需的受控输入。 */
+export interface ToListTableOptionsInput<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 当前语义列。 */
+    columns: readonly TtVTableColumn<Row, Key>[];
+    /** 当前稳定公共 API。 */
+    tableApi: TtVTableApi<Row, Key>;
+    /** 当前组件可用的 Vue renderer 插槽。 */
+    rendererSlots: TtVTableRendererSlots<Row, Key>;
+    /** 从记录读取业务主键。 */
+    getRowKey: (record: Row) => Key;
+    /** 安全原生 options。 */
+    nativeOptions?: TtVTableNativeOptions;
+    /** Vue DOM 渲染配置。 */
+    rendering?: TtVTableRenderingOptions;
+    /** 当前 Vue appContext 读取函数。 */
+    getVueUserAppContext?: () => unknown;
+}
+/**
+ * 创建不携带业务 records 的稳定 ListTable options。
+ * @param input 语义列、API、插槽与安全原生配置
+ * @returns 可交给官方 Vue ListTable 的 options
+ */
+export declare function toListTableOptions<Row extends Record<string, unknown>, Key extends TtVTableRowKey>(input: ToListTableOptionsInput<Row, Key>): ListTableConstructorOptions;

package/dist/components/tt-vtable/src/engine/visactor/toListTableOptions.js

@@ -0,0 +1,25 @@
+import { validateNativeOptions as a } from "./native-boundaries.js";
+import { toFrozenColumnOrder as i, getFrozenColumnCounts as c, getColumnDomCacheCount as l, toColumnDefinitions as u } from "./toColumnDefinitions.js";
+function v(o) {
+  var t, n;
+  a(o.nativeOptions);
+  const e = i(o.columns), r = c(e), s = ((t = o.rendering) == null ? void 0 : t.maxDomCacheCount) ?? l(e) ?? 100, C = {
+    ...((n = o.nativeOptions) == null ? void 0 : n.customConfig) ?? {},
+    createReactContainer: !0,
+    maxDomCacheCount: s,
+    getVueUserAppContext: o.getVueUserAppContext
+  }, m = u(e, {
+    tableApi: o.tableApi,
+    rendererSlots: o.rendererSlots,
+    getRowKey: o.getRowKey
+  });
+  return {
+    ...o.nativeOptions,
+    ...r,
+    columns: m,
+    customConfig: C
+  };
+}
+export {
+  v as toListTableOptions
+};

package/dist/components/tt-vtable/src/engine/visactor/types.d.ts

@@ -0,0 +1,29 @@
+import { ColumnDefine, ListTable, ListTableConstructorOptions, TYPES } from '@visactor/vtable';
+import { TtVTableFieldPath } from '../../public';
+/** VTable 用于定位根记录或树节点的源索引。 */
+export type VisactorRecordIndex = number | number[];
+/** VisActor 实例与封装层之间的受控适配器。 */
+export interface VisactorTableEngine<Row extends Record<string, unknown>> {
+    /** 返回当前原生实例。 */
+    getInstance: () => ListTable | undefined;
+    /** 使用新的运行时根列表全量替换记录。 */
+    setRecords: (records: Row[]) => void;
+    /** 在指定源索引前追加或插入记录。 */
+    addRecords: (records: Row[], recordIndex?: VisactorRecordIndex) => void;
+    /** 一次更新多条根记录或树节点。 */
+    updateRecords: (records: Row[], recordIndexes: VisactorRecordIndex[]) => void;
+    /** 按源索引删除多条根记录或树节点。 */
+    deleteRecords: (recordIndexes: VisactorRecordIndex[]) => void;
+    /** 精确刷新一个单元格，无法映射到可见坐标时返回 false。 */
+    changeCellValue: (recordIndex: VisactorRecordIndex, field: TtVTableFieldPath, value: unknown) => boolean;
+    /** 使用结构配置更新原生实例。 */
+    updateOptions: (options: ListTableConstructorOptions) => Promise<unknown>;
+    /** 使用原生增量接口替换列。 */
+    updateColumns: (columns: ColumnDefine[]) => void;
+    /** 使用原生分页接口更新本地分页。 */
+    updatePagination: (pagination: TYPES.IPagination) => void;
+    /** 重新计算当前布局。 */
+    recalculate: () => void;
+    /** 幂等释放适配器持有的引用。 */
+    release: () => void;
+}

package/dist/components/tt-vtable/src/features/column-preferences/column-preference-storage.d.ts

@@ -0,0 +1,36 @@
+import { TtVTableColumn } from '../../public/table-column';
+/** 封装层支持持久化的冻结列位置。 */
+export type VTableColumnFrozen = NonNullable<TtVTableColumn["frozen"]>;
+/** 一个语义列主键的持久化偏好。 */
+export interface VTableColumnPreference {
+    /** 稳定语义列主键。 */
+    key: string;
+    /** 列是否可见。 */
+    visible: boolean;
+    /** 在同级列中从 0 开始的顺序。 */
+    order: number;
+    /** 可选数字列宽。 */
+    width?: number;
+    /** 可选冻结位置。 */
+    frozen?: VTableColumnFrozen;
+}
+/** 带版本的列偏好载荷。 */
+export interface VTableColumnPreferenceSnapshot {
+    /** 用于后续迁移的 schema 版本。 */
+    schemaVersion: number;
+    /** 按语义列主键索引的偏好。 */
+    columns: readonly VTableColumnPreference[];
+}
+/** 本地或服务端列偏好的异步持久化边界。 */
+export interface VTableColumnPreferenceStorage {
+    /** 读取已保存快照。 */
+    read: (key: string) => Promise<VTableColumnPreferenceSnapshot | undefined>;
+    /** 写入完整快照。 */
+    write: (key: string, snapshot: VTableColumnPreferenceSnapshot) => Promise<void>;
+    /** 删除已保存快照。 */
+    remove: (key: string) => Promise<void>;
+}
+/** 判断未知值是否为有效的带版本偏好快照。 */
+export declare function isColumnPreferenceSnapshot(value: unknown): value is VTableColumnPreferenceSnapshot;
+/** 创建 SSR 安全的默认 localStorage 偏好适配器。 */
+export declare function createLocalColumnPreferenceStorage(): VTableColumnPreferenceStorage;