@dazhicheng/ui 1.6.7 → 1.6.9

package/dist/components/tt-vtable/src/features/querying/useRecordQuery.d.ts

@@ -0,0 +1,38 @@
+import { MaybeRefOrGetter, Ref } from 'vue';
+import { TtVTableFetchRequest, TtVTableFetchResponse } from '../../public/table-props';
+/** 挂载 AbortSignal 前用于发起请求的快照。 */
+export type VTableRecordRequestSnapshot<QueryParams extends Record<string, unknown>> = Omit<TtVTableFetchRequest<QueryParams>, "signal">;
+/** 暴露给 runtime 的远程查询状态与动作。 */
+export interface VTableRecordQuery<QueryParams extends Record<string, unknown>> {
+    /** 最新请求是否进行中。 */
+    isFetching: Readonly<Ref<boolean>>;
+    /** 最近一次被接纳请求的错误。 */
+    error: Readonly<Ref<Error | undefined>>;
+    /** 使用当前状态和可选覆盖参数执行请求。 */
+    fetch: (overrides?: Partial<VTableRecordRequestSnapshot<QueryParams>>) => Promise<boolean>;
+    /** 不重置分页并重放最近一次被接纳的请求。 */
+    refresh: () => Promise<boolean>;
+    /** 取消当前请求并使其响应失效。 */
+    cancel: () => void;
+}
+/** 远程查询 feature 所需依赖。 */
+export interface UseRecordQueryOptions<Row, QueryParams extends Record<string, unknown>> {
+    /** 远程记录请求回调。 */
+    fetchRecords: (request: TtVTableFetchRequest<QueryParams>) => Promise<TtVTableFetchResponse<Row>>;
+    /** 读取最新请求状态。 */
+    getRequestSnapshot: () => VTableRecordRequestSnapshot<QueryParams>;
+    /** 最新请求成功后替换 runtime 记录。 */
+    replaceRecords: (records: readonly Row[]) => Promise<void> | void;
+    /** 最新请求成功后保存总数。 */
+    setTotal: (total: number) => void;
+    /** 仅按根引用监听的 maybe-reactive 查询参数。 */
+    queryParams?: MaybeRefOrGetter<QueryParams>;
+    /** 是否立即执行首次请求。 */
+    immediate?: boolean;
+    /** 最新请求被接纳后调用。 */
+    onSuccess?: (response: TtVTableFetchResponse<Row>, request: TtVTableFetchRequest<QueryParams>) => void;
+    /** 最新且未中止的请求失败时调用。 */
+    onError?: (error: Error, request: TtVTableFetchRequest<QueryParams>) => void;
+}
+/** 创建可防止请求竞态的远程记录查询 feature。 */
+export declare function useRecordQuery<Row, QueryParams extends Record<string, unknown> = Record<string, unknown>>(options: UseRecordQueryOptions<Row, QueryParams>): VTableRecordQuery<QueryParams>;

package/dist/components/tt-vtable/src/features/querying/useRecordQuery.js

@@ -0,0 +1,57 @@
+import "axios";
+import "element-plus";
+import { isError as p } from "../../../../../packages/utils/src/is.js";
+import { shallowRef as h, watch as E, toValue as v, onScopeDispose as R } 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 w(r) {
+  return new Error(p(r) ? String(r).replace(/^Error:\s*/, "") : String(r));
+}
+function y(r) {
+  return r.name === "AbortError";
+}
+function I(r) {
+  const c = h(!1), n = h();
+  let e, t = 0, o;
+  async function i(S = {}) {
+    var d, q;
+    e == null || e.abort(), e = new AbortController(), t += 1;
+    const s = t, m = { ...r.getRequestSnapshot(), ...S }, a = {
+      ...m,
+      signal: e.signal
+    };
+    c.value = !0, n.value = void 0;
+    try {
+      const u = await r.fetchRecords(a);
+      return s !== t || a.signal.aborted || (await r.replaceRecords(u.records), s !== t || a.signal.aborted) ? !1 : (r.setTotal(u.total), o = m, (d = r.onSuccess) == null || d.call(r, u, a), !0);
+    } catch (u) {
+      const l = w(u);
+      return s !== t || a.signal.aborted || y(l) || (n.value = l, (q = r.onError) == null || q.call(r, l, a)), !1;
+    } finally {
+      s === t && (c.value = !1);
+    }
+  }
+  function g() {
+    return i(o);
+  }
+  function f() {
+    t += 1, e == null || e.abort(), e = void 0, c.value = !1;
+  }
+  return r.queryParams ? E(
+    () => v(r.queryParams),
+    () => void i(),
+    { immediate: r.immediate ?? !0 }
+  ) : (r.immediate ?? !0) && i(), R(f), { isFetching: c, error: n, fetch: i, refresh: g, cancel: f };
+}
+export {
+  I as useRecordQuery
+};

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

@@ -0,0 +1,3 @@
+/** TtVTable records feature 与 rowKey 索引。 */
+export * from './record-index';
+export * from './useRecordSource';

package/dist/components/tt-vtable/src/features/records/record-index.d.ts

@@ -0,0 +1,122 @@
+import { TtVTableFieldPath, TtVTableRowKey, TtVTableRowKeySource } from '../../public';
+/** 根记录或树节点在源 records 中的索引路径。 */
+export type TtVTableRecordPath = readonly number[];
+/** rowKey 索引中的一条记录位置。 */
+export interface TtVTableRecordLocation<Row, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 当前业务主键。 */
+    rowKey: Key;
+    /** 当前运行时记录。 */
+    record: Row;
+    /** 从根 records 到当前记录的源索引路径。 */
+    path: TtVTableRecordPath;
+}
+/**
+ * 把字段路径规范为可逐层读取的片段。
+ * @param field 字段或点分隔字段路径
+ * @returns 路径片段
+ */
+export declare function toFieldSegments(field: TtVTableFieldPath): (number | string)[];
+/**
+ * 按字段路径读取记录值。
+ * @param record 业务记录
+ * @param field 字段或点分隔字段路径
+ * @returns 路径对应值
+ */
+export declare function getRecordFieldValue<Row extends Record<string, unknown>>(record: Readonly<Row>, field: TtVTableFieldPath): unknown;
+/**
+ * 判断值是否是合法业务主键。
+ * @param rowKey 待判断主键
+ * @returns 是否为非空字符串或有限数字
+ */
+export declare function isValidVTableRowKey(rowKey: unknown): rowKey is TtVTableRowKey;
+/**
+ * 按字段路径创建只复制命中分支的新记录。
+ * @param record 原记录
+ * @param field 字段或点分隔字段路径
+ * @param value 待写值
+ * @returns 更新后的记录
+ */
+export declare function toRecordWithFieldValue<Row extends Record<string, unknown>>(record: Row, field: TtVTableFieldPath, value: unknown): Row;
+/**
+ * 按字段路径直接修改共享记录。
+ * @param record 共享记录
+ * @param field 字段或点分隔字段路径
+ * @param value 待写值
+ */
+export declare function setSharedRecordFieldValue<Row extends Record<string, unknown>>(record: Row, field: TtVTableFieldPath, value: unknown): void;
+/**
+ * 按源索引路径读取根记录或树节点。
+ * @param records 根记录集合
+ * @param path 源索引路径
+ * @param childrenField 子节点字段路径
+ * @returns 命中的记录
+ */
+export declare function getRecordAtPath<Row extends Record<string, unknown>>(records: readonly Row[], path: TtVTableRecordPath, childrenField: string): Row | undefined;
+/**
+ * 在运行时根数组中替换记录，并只复制树路径上的父分支。
+ * @param records 运行时根记录数组
+ * @param path 目标源索引路径
+ * @param nextRecord 更新后的目标记录
+ * @param childrenField 子节点字段路径
+ */
+export declare function replaceRecordAtPath<Row extends Record<string, unknown>>(records: Row[], path: TtVTableRecordPath, nextRecord: Row, childrenField: string): void;
+/** 维护 rowKey 到源索引路径的稳定映射。 */
+export declare class TtVTableRecordIndex<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 业务主键字段路径或读取函数。 */
+    private readonly rowKeySource;
+    /** 子节点字段路径。 */
+    private readonly childrenField;
+    /** 当前主键位置映射。 */
+    private locations;
+    /**
+     * 创建空 rowKey 索引。
+     * @param rowKeySource 业务主键字段路径或读取函数
+     * @param childrenField 子节点字段路径
+     */
+    constructor(rowKeySource: TtVTableRowKeySource<Row, Key>, childrenField?: string);
+    /** 当前索引记录数量。 */
+    get size(): number;
+    /**
+     * 从业务记录读取并校验主键。
+     * @param record 业务记录
+     * @returns 合法业务主键
+     */
+    getRowKey(record: Row): Key;
+    /**
+     * 使用新的根记录重建并原子替换索引。
+     * @param records 运行时根记录
+     */
+    replace(records: readonly Row[]): void;
+    /**
+     * 判断索引是否包含主键。
+     * @param rowKey 业务主键
+     * @returns 是否存在
+     */
+    has(rowKey: Key): boolean;
+    /**
+     * 按主键读取位置。
+     * @param rowKey 业务主键
+     * @returns 当前记录位置
+     */
+    getLocation(rowKey: Key): TtVTableRecordLocation<Row, Key> | undefined;
+    /**
+     * 按主键读取记录。
+     * @param rowKey 业务主键
+     * @returns 当前运行时记录
+     */
+    getRecord(rowKey: Key): Row | undefined;
+    /**
+     * 原子迁移一条记录的主键、引用和路径。
+     * @param previousRowKey 变化前主键
+     * @param nextRowKey 变化后主键
+     * @param record 更新后的记录
+     * @param path 当前源索引路径
+     */
+    replaceLocation(previousRowKey: Key, nextRowKey: Key, record: Row, path: TtVTableRecordPath): void;
+    /**
+     * 更新 copy-on-write 后树分支上的记录引用。
+     * @param records 当前运行时根记录
+     * @param path 已修改记录路径
+     */
+    refreshBranch(records: readonly Row[], path: TtVTableRecordPath): void;
+}

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

@@ -0,0 +1,209 @@
+var b = Object.defineProperty;
+var E = (r, t, o) => t in r ? b(r, t, { enumerable: !0, configurable: !0, writable: !0, value: o }) : r[t] = o;
+var f = (r, t, o) => E(r, typeof t != "symbol" ? t + "" : t, o);
+import "axios";
+import "element-plus";
+import { isFunction as F, isArray as u, isNumber as g, isString as I, isObject 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 m } from "../../public/table-errors.js";
+function L(r) {
+  return g(r) ? [r] : r.split(".").filter(Boolean);
+}
+function V(r) {
+  return T(r) || u(r);
+}
+function w(r, t) {
+  return u(r) ? g(t) ? r[t] : void 0 : r[t];
+}
+function p(r, t) {
+  let o = r;
+  const e = L(t);
+  for (const i of e) {
+    if (!V(o)) return;
+    o = w(o, i);
+  }
+  return o;
+}
+function K(r) {
+  return I(r) ? !!r : g(r) && Number.isFinite(r);
+}
+function y(r) {
+  return u(r) ? [...r] : T(r) ? { ...r } : {};
+}
+function R(r, t, o) {
+  if (u(r)) {
+    g(t) && (r[t] = o);
+    return;
+  }
+  r[t] = o;
+}
+function A(r, t, o) {
+  const e = L(t);
+  if (!e.length) return r;
+  const i = { ...r };
+  let c = r, n = i;
+  return e.forEach((s, l) => {
+    if (l === e.length - 1) {
+      R(n, s, o);
+      return;
+    }
+    const h = V(c) ? w(c, s) : void 0, d = y(h);
+    R(n, s, d), c = h, n = d;
+  }), i;
+}
+function _(r, t, o) {
+  let e = r, i;
+  for (let c = 0; c < t.length; c += 1) {
+    const n = t[c];
+    if (n === void 0 || (i = e[n], !i)) return;
+    if (c === t.length - 1) return i;
+    const s = p(i, o);
+    if (!u(s)) return;
+    e = s;
+  }
+  return i;
+}
+function q(r, t, o, e) {
+  if (!t.length) return;
+  if (t.length === 1) {
+    const n = t[0];
+    if (n === void 0) return;
+    r[n] = o;
+    return;
+  }
+  let i = o;
+  for (let n = t.length - 2; n >= 0; n -= 1) {
+    const s = t.slice(0, n + 1), l = _(r, s, e);
+    if (!l) return;
+    const a = p(l, e);
+    if (!u(a)) return;
+    const h = [...a], d = t[n + 1];
+    if (d === void 0) return;
+    h[d] = i, i = A(l, e, h);
+  }
+  const c = t[0];
+  c !== void 0 && (r[c] = i);
+}
+class G {
+  /**
+   * 创建空 rowKey 索引。
+   * @param rowKeySource 业务主键字段路径或读取函数
+   * @param childrenField 子节点字段路径
+   */
+  constructor(t, o = "children") {
+    /** 业务主键字段路径或读取函数。 */
+    f(this, "rowKeySource");
+    /** 子节点字段路径。 */
+    f(this, "childrenField");
+    /** 当前主键位置映射。 */
+    f(this, "locations", /* @__PURE__ */ new Map());
+    this.rowKeySource = t, this.childrenField = o;
+  }
+  /** 当前索引记录数量。 */
+  get size() {
+    return this.locations.size;
+  }
+  /**
+   * 从业务记录读取并校验主键。
+   * @param record 业务记录
+   * @returns 合法业务主键
+   */
+  getRowKey(t) {
+    const o = F(this.rowKeySource) ? this.rowKeySource(t) : p(t, this.rowKeySource);
+    if (!K(o))
+      throw m("TT_VTABLE_ROW_KEY_INVALID", "rowKey 必须是非空字符串或有限数字。", { rowKey: o });
+    return o;
+  }
+  /**
+   * 使用新的根记录重建并原子替换索引。
+   * @param records 运行时根记录
+   */
+  replace(t) {
+    const o = /* @__PURE__ */ new Map(), e = (i, c) => {
+      i.forEach((n, s) => {
+        const l = this.getRowKey(n);
+        if (o.has(l))
+          throw m("TT_VTABLE_DUPLICATE_ROW_KEY", `rowKey ${String(l)} 在整棵记录树中重复。`, {
+            rowKey: l
+          });
+        const a = [...c, s];
+        o.set(l, { rowKey: l, record: n, path: a });
+        const h = p(n, this.childrenField);
+        u(h) && h.length && e(h, a);
+      });
+    };
+    e(t, []), this.locations = o;
+  }
+  /**
+   * 判断索引是否包含主键。
+   * @param rowKey 业务主键
+   * @returns 是否存在
+   */
+  has(t) {
+    return this.locations.has(t);
+  }
+  /**
+   * 按主键读取位置。
+   * @param rowKey 业务主键
+   * @returns 当前记录位置
+   */
+  getLocation(t) {
+    return this.locations.get(t);
+  }
+  /**
+   * 按主键读取记录。
+   * @param rowKey 业务主键
+   * @returns 当前运行时记录
+   */
+  getRecord(t) {
+    var o;
+    return (o = this.locations.get(t)) == null ? void 0 : o.record;
+  }
+  /**
+   * 原子迁移一条记录的主键、引用和路径。
+   * @param previousRowKey 变化前主键
+   * @param nextRowKey 变化后主键
+   * @param record 更新后的记录
+   * @param path 当前源索引路径
+   */
+  replaceLocation(t, o, e, i) {
+    if (o !== t && this.locations.has(o))
+      throw m("TT_VTABLE_DUPLICATE_ROW_KEY", `rowKey ${String(o)} 已存在。`, {
+        rowKey: o
+      });
+    this.locations.delete(t), this.locations.set(o, { rowKey: o, record: e, path: [...i] });
+  }
+  /**
+   * 更新 copy-on-write 后树分支上的记录引用。
+   * @param records 当前运行时根记录
+   * @param path 已修改记录路径
+   */
+  refreshBranch(t, o) {
+    for (let e = 1; e <= o.length; e += 1) {
+      const i = o.slice(0, e), c = _(t, i, this.childrenField);
+      if (!c) continue;
+      const n = this.getRowKey(c), s = this.locations.get(n);
+      s && (s.record = c, s.path = i);
+    }
+  }
+}
+export {
+  G as TtVTableRecordIndex,
+  _ as getRecordAtPath,
+  p as getRecordFieldValue,
+  K as isValidVTableRowKey,
+  q as replaceRecordAtPath,
+  L as toFieldSegments,
+  A as toRecordWithFieldValue
+};

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

@@ -0,0 +1,41 @@
+import { TtVTableMutationMode, TtVTableRecordChange, TtVTableRecordsApi, TtVTableRowKey, TtVTableRowKeySource } from '../../public';
+import { VisactorRecordIndex, VisactorTableEngine } from '../../engine/visactor';
+import { TtVTableRecordIndex } from './record-index';
+/** records feature 依赖。 */
+export interface UseRecordSourceOptions<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 初始本地或远程记录。 */
+    records?: readonly Row[];
+    /** 业务主键字段路径或读取函数。 */
+    rowKey: TtVTableRowKeySource<Row, Key>;
+    /** 子节点字段路径。 */
+    childrenField?: string;
+    /** 记录所有权策略。 */
+    mutationMode?: TtVTableMutationMode;
+    /** 稳定 VisActor 适配器。 */
+    engine: VisactorTableEngine<Row>;
+    /** 接收 API 或 renderer 产生的精确记录变化。 */
+    onRecordChange?: (change: TtVTableRecordChange<Row, Key>) => void;
+    /** 根记录替换后的协调回调。 */
+    onRecordsReplaced?: (records: readonly Row[]) => void;
+}
+/** records feature 提供给 runtime 和其他 feature 的完整契约。 */
+export interface TtVTableRecordSource<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey> extends TtVTableRecordsApi<Row, Key> {
+    /** 当前 rowKey 索引。 */
+    recordIndex: TtVTableRecordIndex<Row, Key>;
+    /** 从记录读取并校验业务主键。 */
+    getRowKey: (record: Row) => Key;
+    /** 按主键读取原生源索引。 */
+    getRecordIndex: (rowKey: Key) => VisactorRecordIndex | undefined;
+    /** 为树 feature 写入 copy-on-write 子节点。 */
+    setChildren: (parentKey: Key, children: readonly Row[]) => void;
+    /** 原生实例 ready 后只同步最终记录快照。 */
+    syncToEngine: () => void;
+    /** 幂等释放 feature。 */
+    release: () => void;
+}
+/**
+ * 创建浅层运行时 records、rowKey 索引和增量更新动作。
+ * @param options 初始记录、主键、所有权策略和 VisActor 适配器
+ * @returns records feature
+ */
+export declare function useRecordSource<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey>(options: UseRecordSourceOptions<Row, Key>): TtVTableRecordSource<Row, Key>;