@dazhicheng/ui 1.6.7 → 1.6.9

package/dist/components/tt-vtable/src/features/records/useRecordSource.js

@@ -0,0 +1,249 @@
+import "axios";
+import "element-plus";
+import { isArray as _, isString as J } from "../../../../../packages/utils/src/is.js";
+import { shallowRef as Q, computed as B, triggerRef as h } 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 y } from "../../public/table-errors.js";
+import { TtVTableRecordIndex as S, getRecordAtPath as N, getRecordFieldValue as p, toRecordWithFieldValue as I, replaceRecordAtPath as A } from "./record-index.js";
+function F(o) {
+  return _(o) ? [...o] : [o];
+}
+function x(o) {
+  const u = o[0];
+  if (u === void 0)
+    throw y("TT_VTABLE_RECORD_NOT_FOUND", "记录索引路径不能为空。", {});
+  return o.length === 1 ? u : [...o];
+}
+function X(o) {
+  return J(o) && o.includes(".");
+}
+function Z(o, u) {
+  if (o.length !== u.length) return u.length - o.length;
+  for (let a = 0; a < o.length; a += 1) {
+    const c = o[a], i = u[a];
+    if (!(c === void 0 || i === void 0) && c !== i)
+      return i - c;
+  }
+  return 0;
+}
+function C(o, u, a) {
+  if (u.length === 1) {
+    const v = u[0];
+    v !== void 0 && o.splice(v, 1);
+    return;
+  }
+  const c = u.slice(0, -1), i = N(o, c, a);
+  if (!i) return;
+  const w = p(i, a);
+  if (!_(w)) return;
+  const g = [...w], K = u[u.length - 1];
+  if (K === void 0) return;
+  g.splice(K, 1);
+  const f = I(i, a, g);
+  A(o, c, f, a);
+}
+function ee(o, u, a) {
+  if (u.length <= 1) return;
+  const c = u.slice(0, -1), i = N(o, c, a);
+  if (!i) return;
+  const w = p(i, a);
+  if (!_(w)) return;
+  const g = I(i, a, [...w]);
+  A(o, c, g, a);
+}
+function xe(o) {
+  const u = o.childrenField || "children", a = o.mutationMode ?? "copy-on-write", c = Q([]), i = new S(o.rowKey, u);
+  let w = !1;
+  const g = B(() => c.value), K = B(() => c.value.length);
+  function f() {
+    if (w)
+      throw y("TT_VTABLE_RELEASED", "records feature 已经释放。", {});
+  }
+  function v() {
+    return c.value;
+  }
+  function U(e) {
+    return i.getRecord(e);
+  }
+  function m(e) {
+    return i.getRowKey(e);
+  }
+  function M(e) {
+    const t = i.getLocation(e);
+    return t ? x(t.path) : void 0;
+  }
+  function L(e) {
+    var s;
+    f();
+    const t = [...e];
+    i.replace(t), c.value = t, o.engine.setRecords(t), (s = o.onRecordsReplaced) == null || s.call(o, t);
+  }
+  function V(e, t) {
+    const s = [...c.value], n = t ?? s.length;
+    s.splice(n, 0, ...e), new S(o.rowKey, u).replace(s), c.value.splice(n, 0, ...e), o.engine.getInstance() && o.engine.addRecords(e, n), i.replace(c.value), h(c);
+  }
+  function P(e) {
+    f();
+    const t = F(e);
+    t.length && V(t);
+  }
+  function b(e, t) {
+    f();
+    const s = Number.isFinite(e) ? Math.max(0, Math.min(Math.floor(e), c.value.length)) : c.value.length, n = F(t);
+    n.length && V(n, s);
+  }
+  function $(e, t) {
+    return { ...e, ...t };
+  }
+  function O(e, t, s) {
+    const n = i.getLocation(e);
+    if (!n)
+      throw y("TT_VTABLE_RECORD_NOT_FOUND", `未找到 rowKey ${String(e)}。`, { rowKey: e });
+    const l = a === "shared" ? { ...n.record } : n.record, R = $(n.record, t), r = m(R), d = Object.keys(t);
+    return {
+      location: n,
+      previousRecord: l,
+      nextRecord: R,
+      previousRowKey: e,
+      nextRowKey: r,
+      changedFields: d,
+      source: s
+    };
+  }
+  function T(e, t = !0) {
+    a === "copy-on-write" ? A(c.value, e.location.path, e.nextRecord, u) : (Object.assign(e.location.record, e.nextRecord), e.nextRecord = e.location.record), t && (i.replaceLocation(
+      e.previousRowKey,
+      e.nextRowKey,
+      e.nextRecord,
+      e.location.path
+    ), i.refreshBranch(c.value, e.location.path));
+  }
+  function E(e) {
+    var t;
+    e.source === "editing" || e.source === "tree" || (t = o.onRecordChange) == null || t.call(o, {
+      rowKey: e.previousRowKey,
+      nextRowKey: e.nextRowKey,
+      record: e.nextRecord,
+      previousRecord: e.previousRecord,
+      changedFields: e.changedFields,
+      source: e.source
+    });
+  }
+  function W(e, t, s = "api") {
+    f();
+    const n = O(e, t, s);
+    if (n.nextRowKey !== e && i.has(n.nextRowKey))
+      throw y("TT_VTABLE_DUPLICATE_ROW_KEY", `rowKey ${String(n.nextRowKey)} 已存在。`, {
+        rowKey: n.nextRowKey
+      });
+    T(n), o.engine.updateRecords([n.nextRecord], [x(n.location.path)]), n.changedFields.includes(u) && i.replace(c.value), h(c), E(n);
+  }
+  function Y(e) {
+    if (f(), !e.length) return;
+    const t = /* @__PURE__ */ new Map();
+    e.forEach((r) => {
+      const d = t.get(r.rowKey);
+      t.set(r.rowKey, {
+        rowKey: r.rowKey,
+        changes: { ...d == null ? void 0 : d.changes, ...r.changes },
+        source: r.source ?? (d == null ? void 0 : d.source) ?? "api"
+      });
+    });
+    const s = [...t.values()].map(
+      (r) => O(r.rowKey, r.changes, r.source ?? "api")
+    ), n = new Set(s.map((r) => r.previousRowKey)), l = /* @__PURE__ */ new Set();
+    s.forEach((r) => {
+      if (l.has(r.nextRowKey) || i.has(r.nextRowKey) && !n.has(r.nextRowKey))
+        throw y(
+          "TT_VTABLE_DUPLICATE_ROW_KEY",
+          `rowKey ${String(r.nextRowKey)} 在批量更新后重复。`,
+          { rowKey: r.nextRowKey }
+        );
+      l.add(r.nextRowKey);
+    });
+    const R = s.some(
+      (r) => r.previousRowKey !== r.nextRowKey || r.changedFields.includes(u)
+    );
+    s.forEach((r) => T(r, !R)), R && i.replace(c.value), o.engine.updateRecords(
+      s.map((r) => r.nextRecord),
+      s.map((r) => x(r.location.path))
+    ), h(c), s.forEach(E);
+  }
+  function j(e, t, s, n) {
+    const l = i.getLocation(e);
+    if (!l)
+      throw y("TT_VTABLE_RECORD_NOT_FOUND", `未找到 rowKey ${String(e)}。`, { rowKey: e });
+    const R = a === "shared" ? { ...l.record } : l.record;
+    if (p(R, t) === s) return;
+    const d = I(l.record, t, s), H = m(d);
+    return {
+      location: l,
+      previousRecord: R,
+      nextRecord: d,
+      previousRowKey: e,
+      nextRowKey: H,
+      changedFields: [t],
+      source: n
+    };
+  }
+  function D(e, t, s, n = "api") {
+    f();
+    const l = j(e, t, s, n);
+    if (!l) return;
+    if (l.nextRowKey !== e && i.has(l.nextRowKey))
+      throw y("TT_VTABLE_DUPLICATE_ROW_KEY", `rowKey ${String(l.nextRowKey)} 已存在。`, {
+        rowKey: l.nextRowKey
+      });
+    T(l);
+    const R = x(l.location.path);
+    (X(t) ? !1 : o.engine.changeCellValue(R, t, s)) || o.engine.updateRecords([l.nextRecord], [R]), t === u && i.replace(c.value), h(c), E(l);
+  }
+  function k(e) {
+    f();
+    const t = [...new Set(e)].map((n) => i.getLocation(n)).filter((n) => !!n).sort((n, l) => Z(n.path, l.path));
+    if (!t.length) return;
+    const s = t.map((n) => x(n.path));
+    a === "copy-on-write" && t.forEach((n) => ee(c.value, n.path, u)), t.forEach((n) => C(c.value, n.path, u)), o.engine.getInstance() && o.engine.deleteRecords(s), i.replace(c.value), h(c);
+  }
+  function z(e, t) {
+    D(e, u, [...t], "tree");
+  }
+  function q() {
+    f(), o.engine.setRecords(c.value);
+  }
+  function G() {
+    w || (w = !0);
+  }
+  return L(o.records ?? []), {
+    records: g,
+    count: K,
+    getAll: v,
+    getByKey: U,
+    replaceAll: L,
+    append: P,
+    insertAt: b,
+    patchByKey: W,
+    patchMany: Y,
+    setCellValue: D,
+    removeByKeys: k,
+    recordIndex: i,
+    getRowKey: m,
+    getRecordIndex: M,
+    setChildren: z,
+    syncToEngine: q,
+    release: G
+  };
+}
+export {
+  xe as useRecordSource
+};

package/dist/components/tt-vtable/src/features/selection/useRowSelection.d.ts

@@ -0,0 +1,65 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
+import { TtVTableRowKey } from '../../public/table-api';
+import { TtVTableSelectionOptions } from '../../public/table-props';
+/** 支持的行选择模式。 */
+export type VTableSelectionMode = NonNullable<TtVTableSelectionOptions<unknown>["mode"]>;
+/** 暴露给表格 runtime 的选择状态。 */
+export interface VTableSelectionState<Row, Key extends TtVTableRowKey> {
+    /** 按选择顺序稳定排列的主键。 */
+    keys: ComputedRef<readonly Key[]>;
+    /** 当前 runtime 数据源中仍存在的已选记录。 */
+    loadedRows: ComputedRef<readonly Row[]>;
+    /** 当前 runtime 数据源中不存在的已选主键。 */
+    missingKeys: ComputedRef<readonly Key[]>;
+    /** 是否正在把公共 model 同步到原生选择状态。 */
+    isSyncingNative: Readonly<Ref<boolean>>;
+}
+/** 挂载到表格命名空间 API 的选择动作。 */
+export interface VTableSelectionActions<Row, Key extends TtVTableRowKey> {
+    /** 替换全部已选主键。 */
+    setKeys: (keys: readonly Key[]) => void;
+    /** 按主键切换一条记录的选择状态。 */
+    toggleKey: (key: Key, selected?: boolean) => void;
+    /** 选择当前页全部可选记录。 */
+    selectCurrentPage: () => void;
+    /** 选择 runtime 当前已加载的全部可选记录。 */
+    selectLoadedRecords: () => void;
+    /** 清空选择。 */
+    clear: () => void;
+    /** 判断记录是否允许选择。 */
+    isSelectable: (record: Row) => boolean;
+}
+/** 完整的选择 feature 契约。 */
+export interface VTableRowSelection<Row, Key extends TtVTableRowKey> extends VTableSelectionState<Row, Key>, VTableSelectionActions<Row, Key> {
+    /** 接收并应用 VTable 的 checkbox 或 radio 变化。 */
+    onNativeSelectionChange: (record: Row, selected: boolean) => void;
+    /** runtime 记录源变化后校正已选主键。 */
+    reconcileRecords: () => void;
+    /** 原生实例 ready 后同步最终选择状态。 */
+    syncNativeState: () => Promise<void>;
+}
+/** 行选择 feature 所需依赖。 */
+export interface UseRowSelectionOptions<Row, Key extends TtVTableRowKey> {
+    /** 选择模式。 */
+    mode: MaybeRefOrGetter<VTableSelectionMode>;
+    /** 公共 selected-row-keys model。 */
+    selectedRowKeys: Ref<Key[]>;
+    /** 读取 runtime 当前加载的全部记录。 */
+    getLoadedRecords: () => readonly Row[];
+    /** 读取当前本地页或远程页记录。 */
+    getCurrentPageRecords: () => readonly Row[];
+    /** 按业务主键读取一条已加载记录。 */
+    getRecordByKey: (key: Key) => Row | undefined;
+    /** 读取记录的稳定业务主键。 */
+    getRowKey: (record: Row) => Key;
+    /** 可选的业务可选性判断函数。 */
+    isRowSelectable?: (record: Row) => boolean;
+    /** 是否跨远程分页保留未加载主键。 */
+    reserveAcrossPages?: MaybeRefOrGetter<boolean>;
+    /** 返回参与树级联的记录，结果包含源记录。 */
+    getCascadeRecords?: (record: Row) => readonly Row[];
+    /** 把公共主键同步到原生 checkbox 或 radio 视觉状态。 */
+    syncNativeSelection?: (keys: readonly Key[]) => Promise<void> | void;
+}
+/** 创建受控的单选或多选行选择 feature。 */
+export declare function useRowSelection<Row, Key extends TtVTableRowKey = TtVTableRowKey>(options: UseRowSelectionOptions<Row, Key>): VTableRowSelection<Row, Key>;

package/dist/components/tt-vtable/src/features/selection/useRowSelection.js

@@ -0,0 +1,129 @@
+import "axios";
+import "element-plus";
+import { isNumber as L, isString as V } from "../../../../../packages/utils/src/is.js";
+import { shallowRef as F, computed as o, toValue as K, watch as S } 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";
+function M(e) {
+  return V(e) ? !!e : L(e) && Number.isFinite(e);
+}
+function w(e, n) {
+  return e.length === n.length && e.every((u, c) => u === n[c]);
+}
+function O(e) {
+  const n = /* @__PURE__ */ new Set(), u = [];
+  return e.forEach((c) => {
+    !M(c) || n.has(c) || (n.add(c), u.push(c));
+  }), u;
+}
+function p(e) {
+  const n = F(!1);
+  let u = 0;
+  const c = o(() => K(e.mode)), s = o(() => d(e.selectedRowKeys.value)), h = o(() => {
+    const t = [];
+    return s.value.forEach((r) => {
+      const l = e.getRecordByKey(r);
+      l && t.push(l);
+    }), t;
+  }), N = o(() => s.value.filter((t) => !e.getRecordByKey(t)));
+  function d(t) {
+    const r = O(t);
+    return c.value === "none" ? [] : c.value === "single" ? r.slice(0, 1) : r;
+  }
+  function i(t) {
+    return e.isRowSelectable ? e.isRowSelectable(t) : !0;
+  }
+  function a(t) {
+    const r = d(t);
+    w(e.selectedRowKeys.value, r) || (e.selectedRowKeys.value = r);
+  }
+  function b(t) {
+    var l;
+    return (((l = e.getCascadeRecords) == null ? void 0 : l.call(e, t)) ?? [t]).filter(i).map(e.getRowKey);
+  }
+  function m(t, r) {
+    const l = e.getRecordByKey(t);
+    if (!l || !i(l) || c.value === "none") return;
+    const x = s.value.includes(t), R = r ?? !x, A = c.value === "single" ? [t] : b(l);
+    if (c.value === "single") {
+      a(R ? [t] : []);
+      return;
+    }
+    const f = new Set(s.value);
+    A.forEach((g) => {
+      R ? f.add(g) : f.delete(g);
+    }), a([...f]);
+  }
+  function v(t) {
+    if (c.value === "none") return;
+    const r = t.filter(i).map(e.getRowKey);
+    if (c.value === "single") {
+      a(r.slice(0, 1));
+      return;
+    }
+    a([...s.value, ...r]);
+  }
+  function z() {
+    v(e.getCurrentPageRecords());
+  }
+  function B() {
+    v(e.getLoadedRecords());
+  }
+  function C() {
+    a([]);
+  }
+  function q(t, r) {
+    n.value || m(e.getRowKey(t), r);
+  }
+  function E() {
+    K(e.reserveAcrossPages ?? !1) || a(s.value.filter((t) => !!e.getRecordByKey(t)));
+  }
+  async function y(t) {
+    if (!e.syncNativeSelection) return;
+    u += 1;
+    const r = u;
+    n.value = !0;
+    try {
+      await e.syncNativeSelection(t);
+    } finally {
+      r === u && (n.value = !1);
+    }
+  }
+  function P() {
+    return y(s.value);
+  }
+  return S(
+    e.selectedRowKeys,
+    (t) => {
+      const r = d(t);
+      w(t, r) || (e.selectedRowKeys.value = r), y(r);
+    },
+    { immediate: !0 }
+  ), S(c, () => a(e.selectedRowKeys.value)), {
+    keys: s,
+    loadedRows: h,
+    missingKeys: N,
+    isSyncingNative: n,
+    setKeys: a,
+    toggleKey: m,
+    selectCurrentPage: z,
+    selectLoadedRecords: B,
+    clear: C,
+    isSelectable: i,
+    onNativeSelectionChange: q,
+    reconcileRecords: E,
+    syncNativeState: P
+  };
+}
+export {
+  p as useRowSelection
+};

package/dist/components/tt-vtable/src/features/tree/useTreeRecords.d.ts

@@ -0,0 +1,60 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
+import { TtVTableRowKey } from '../../public/table-api';
+import { TtVTableTreeLoadError, TtVTableTreeLoadSuccess } from '../../public/table-events';
+import { TtVTableTreeChildrenRequest } from '../../public/table-props';
+/** 暴露给 runtime 的树状态与动作。 */
+export interface VTableTreeRecords<Row, Key extends TtVTableRowKey> {
+    /** 已展开业务主键。 */
+    expandedKeys: Readonly<Ref<readonly Key[]>>;
+    /** 正在加载子节点的业务主键。 */
+    loadingKeys: Readonly<Ref<readonly Key[]>>;
+    /** 最近一次未中止的树请求错误。 */
+    error: Readonly<Ref<Error | undefined>>;
+    /** 是否至少有一个树请求进行中。 */
+    isLoading: ComputedRef<boolean>;
+    /** 展开节点并在需要时懒加载子节点。 */
+    expand: (key: Key) => Promise<void>;
+    /** 折叠节点且不丢弃已缓存子节点。 */
+    collapse: (key: Key) => void;
+    /** 切换节点展开状态。 */
+    toggle: (key: Key) => Promise<void>;
+    /** 加载节点子记录并复用重复请求。 */
+    fetchChildren: (key: Key) => Promise<readonly Row[]>;
+    /** 应用原生层级状态事件。 */
+    onNativeHierarchyChange: (record: Row, expanded: boolean) => Promise<void>;
+    /** records 根引用变化后使进行中的请求失效。 */
+    onRecordsReplaced: () => void;
+    /** 返回树选择级联使用的已加载后代记录。 */
+    getCascadeRecords: (record: Row) => readonly Row[];
+    /** 原生实例 ready 后同步最终展开快照。 */
+    syncExpandedState: () => Promise<void>;
+    /** 释放进行中的请求和状态。 */
+    release: () => void;
+}
+/** 树记录 feature 所需依赖。 */
+export interface UseTreeRecordsOptions<Row, Key extends TtVTableRowKey> {
+    /** 初始展开主键。 */
+    defaultExpandedKeys?: readonly Key[];
+    /** 按主键读取一条 runtime 记录。 */
+    getRecordByKey: (key: Key) => Row | undefined;
+    /** 读取记录的稳定业务主键。 */
+    getRowKey: (record: Row) => Key;
+    /** 从 runtime 记录读取已加载子记录。 */
+    getChildren: (record: Row) => readonly Row[] | undefined;
+    /** 通过 records feature 写入复制后的子记录。 */
+    setChildren: (parentKey: Key, children: readonly Row[]) => Promise<void> | void;
+    /** 可选的子节点懒加载请求回调。 */
+    fetchTreeChildren?: (request: TtVTableTreeChildrenRequest<Row, Key>) => Promise<readonly Row[]>;
+    /** 后续展开时是否复用已加载子记录。 */
+    cacheChildren?: MaybeRefOrGetter<boolean>;
+    /** 同步一个原生层级状态。 */
+    setNativeExpanded?: (key: Key, expanded: boolean) => Promise<void> | void;
+    /** 同步一个原生层级加载状态。 */
+    setNativeLoading?: (key: Key, loading: boolean) => Promise<void> | void;
+    /** 当前子记录被接纳后调用一次。 */
+    onLoadSuccess?: (change: TtVTableTreeLoadSuccess<Row, Key>) => void;
+    /** 当前未中止请求失败后调用一次。 */
+    onLoadError?: (failure: TtVTableTreeLoadError<Key>) => void;
+}
+/** 创建树展开和可防竞态的懒加载 feature。 */
+export declare function useTreeRecords<Row, Key extends TtVTableRowKey = TtVTableRowKey>(options: UseTreeRecordsOptions<Row, Key>): VTableTreeRecords<Row, Key>;

package/dist/components/tt-vtable/src/features/tree/useTreeRecords.js

@@ -0,0 +1,125 @@
+import "axios";
+import "element-plus";
+import { isArray as G, isError as j } from "../../../../../packages/utils/src/is.js";
+import { shallowRef as E, computed as D, onScopeDispose as H, toValue as M } 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";
+function V(r) {
+  return new Error(j(r) ? String(r).replace(/^Error:\s*/, "") : String(r));
+}
+function x(r, n) {
+  return r.includes(n) ? [...r] : [...r, n];
+}
+function T(r, n) {
+  return r.filter((i) => i !== n);
+}
+function re(r) {
+  const n = E([...new Set(r.defaultExpandedKeys ?? [])]), i = E([]), v = E(), u = /* @__PURE__ */ new Map();
+  let s = 0, h = !1;
+  const L = D(() => i.value.length > 0);
+  async function w(e, t, a = !0) {
+    var c;
+    n.value = t ? x(n.value, e) : T(n.value, e), a && await ((c = r.setNativeExpanded) == null ? void 0 : c.call(r, e, t));
+  }
+  async function K(e, t) {
+    var a;
+    i.value = t ? x(i.value, e) : T(i.value, e), await ((a = r.setNativeLoading) == null ? void 0 : a.call(r, e, t));
+  }
+  function m(e) {
+    const t = u.get(e);
+    if (t) return t.promise;
+    const a = r.getRecordByKey(e);
+    if (!a) return Promise.reject(new Error(`Cannot load children for missing record "${String(e)}".`));
+    const c = r.getChildren(a);
+    if (M(r.cacheChildren ?? !0) && (c != null && c.length) || !r.fetchTreeChildren)
+      return Promise.resolve(c ?? []);
+    const l = new AbortController(), d = s, g = {}, S = (async () => {
+      var q, b;
+      try {
+        await K(e, !0), v.value = void 0;
+        const o = await r.fetchTreeChildren({ parent: a, parentKey: e, signal: l.signal });
+        if (l.signal.aborted || d !== s || h) return [];
+        if (!G(o)) throw new Error("Tree child request must return an array.");
+        const f = [...o];
+        return await r.setChildren(e, f), l.signal.aborted || d !== s || h ? [] : ((q = r.onLoadSuccess) == null || q.call(r, { parentKey: e, children: f }), f);
+      } catch (o) {
+        const f = V(o);
+        if (l.signal.aborted || d !== s || h) return [];
+        throw v.value = f, (b = r.onLoadError) == null || b.call(r, { parentKey: e, error: f }), f;
+      } finally {
+        const o = u.get(e);
+        (o == null ? void 0 : o.token) === g && u.delete(e), d === s && !h && await K(e, !1);
+      }
+    })();
+    return u.set(e, { controller: l, promise: S, token: g }), S;
+  }
+  async function R(e) {
+    await w(e, !0);
+    try {
+      await m(e);
+    } catch (t) {
+      throw await w(e, !1), t;
+    }
+  }
+  function C(e) {
+    w(e, !1);
+  }
+  function N(e) {
+    return n.value.includes(e) ? (C(e), Promise.resolve()) : R(e);
+  }
+  async function p(e, t) {
+    const a = r.getRowKey(e);
+    if (await w(a, t, !1), !!t)
+      try {
+        await m(a);
+      } catch (c) {
+        throw await w(a, !1), c;
+      }
+  }
+  function P() {
+    s += 1, u.forEach((e) => e.controller.abort()), u.clear(), i.value = [], v.value = void 0, n.value = n.value.filter((e) => !!r.getRecordByKey(e));
+  }
+  function A(e) {
+    const t = /* @__PURE__ */ new Set(), a = [];
+    function c(l) {
+      var g;
+      const d = r.getRowKey(l);
+      t.has(d) || (t.add(d), a.push(l), (g = r.getChildren(l)) == null || g.forEach(c));
+    }
+    return c(e), a;
+  }
+  async function B() {
+    var e;
+    for (const t of n.value) await ((e = r.setNativeExpanded) == null ? void 0 : e.call(r, t, !0));
+  }
+  function y() {
+    h || (h = !0, s += 1, u.forEach((e) => e.controller.abort()), u.clear(), i.value = []);
+  }
+  return H(y), {
+    expandedKeys: n,
+    loadingKeys: i,
+    error: v,
+    isLoading: L,
+    expand: R,
+    collapse: C,
+    toggle: N,
+    fetchChildren: m,
+    onNativeHierarchyChange: p,
+    onRecordsReplaced: P,
+    getCascadeRecords: A,
+    syncExpandedState: B,
+    release: y
+  };
+}
+export {
+  re as useTreeRecords
+};

package/dist/components/tt-vtable/src/public/column-preferences.d.ts

@@ -0,0 +1,32 @@
+import { TtVTableColumn } from './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>;
+}

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

@@ -0,0 +1,8 @@
+/** TtVTable 公共 API、列、事件、props、slots 与错误类型。 */
+export * from './column-preferences';
+export * from './table-api';
+export * from './table-column';
+export * from './table-errors';
+export * from './table-events';
+export * from './table-props';
+export * from './table-slots';