@dazhicheng/ui 1.6.7 → 1.6.8

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

@@ -0,0 +1,52 @@
+import "axios";
+import "element-plus";
+import { isClient as n, isObject as m, isNumber as i, isArray as a, isString as p, isBoolean as c, isDef 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";
+const d = "tt-vtable:columns:";
+function S(e) {
+  return c(e) || e === "left" || e === "right";
+}
+function g(e) {
+  if (!m(e)) return !1;
+  const r = e;
+  return p(r.key) && !!r.key && c(r.visible) && i(r.order) && Number.isInteger(r.order) && r.order >= 0 && (!l(r.width) || i(r.width) && r.width > 0) && (!r.frozen || S(r.frozen));
+}
+function h(e) {
+  if (!m(e)) return !1;
+  const r = e;
+  return i(r.schemaVersion) && Number.isInteger(r.schemaVersion) && r.schemaVersion > 0 && a(r.columns) && r.columns.every(g);
+}
+function A() {
+  function e(t) {
+    return `${d}${t}`;
+  }
+  async function r(t) {
+    if (!n || !t) return;
+    const o = window.localStorage.getItem(e(t));
+    if (!o) return;
+    const s = JSON.parse(o);
+    return h(s) ? s : void 0;
+  }
+  async function f(t, o) {
+    !n || !t || window.localStorage.setItem(e(t), JSON.stringify(o));
+  }
+  async function u(t) {
+    !n || !t || window.localStorage.removeItem(e(t));
+  }
+  return { read: r, write: f, remove: u };
+}
+export {
+  A as createLocalColumnPreferenceStorage,
+  h as isColumnPreferenceSnapshot
+};

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

@@ -0,0 +1,74 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
+import { VTableColumnFrozen, VTableColumnPreference, VTableColumnPreferenceSnapshot, VTableColumnPreferenceStorage } from './column-preference-storage';
+/** 列偏好 feature 所需的结构化列字段。 */
+export interface VTablePreferenceColumn<Column> {
+    /** 稳定语义列主键。 */
+    key: string;
+    /** 可选嵌套分组列。 */
+    columns?: readonly Column[];
+    /** 初始可见性。 */
+    visible?: boolean;
+    /** 初始宽度。 */
+    width?: number | string;
+    /** 初始冻结位置。 */
+    frozen?: VTableColumnFrozen;
+}
+/** 面向工具栏的列偏好视图。 */
+export interface VTableColumnPreferenceEntry<Column> extends VTableColumnPreference {
+    /** 当前源列。 */
+    column: Column;
+    /** 在语义列树中的嵌套深度。 */
+    depth: number;
+}
+/** 暴露给 runtime 的列偏好状态与动作。 */
+export interface VTableColumnPreferences<Column> {
+    /** 应用偏好前的源列。 */
+    sourceColumns: Readonly<Ref<readonly Column[]>>;
+    /** 应用偏好后的可见有序列。 */
+    columns: ComputedRef<readonly Column[]>;
+    /** 面向工具栏的全部源列扁平设置。 */
+    entries: ComputedRef<readonly VTableColumnPreferenceEntry<Column>[]>;
+    /** 异步偏好读取是否进行中。 */
+    isLoading: Readonly<Ref<boolean>>;
+    /** 最近一次持久化错误。 */
+    error: Readonly<Ref<Error | undefined>>;
+    /** 替换源列根引用并校正已保存主键。 */
+    replaceAll: (columns: readonly Column[]) => void;
+    /** 显示一个语义列。 */
+    show: (key: string) => void;
+    /** 隐藏一个语义列。 */
+    hide: (key: string) => void;
+    /** 在同级列集合中移动一列。 */
+    move: (key: string, targetIndex: number) => void;
+    /** 保存一个数字列宽。 */
+    setWidth: (key: string, width: number) => void;
+    /** 保存一个冻结位置。 */
+    setFrozen: (key: string, frozen: VTableColumnFrozen | undefined) => void;
+    /** 从配置的 storage 加载偏好。 */
+    load: () => Promise<void>;
+    /** 恢复源列默认值并删除持久化内容。 */
+    resetPreferences: () => Promise<void>;
+}
+/** 列偏好 feature 所需依赖。 */
+export interface UseColumnPreferencesOptions<Column extends VTablePreferenceColumn<Column>> {
+    /** 仅按引用监听的 maybe-reactive 源列根。 */
+    columns: MaybeRefOrGetter<readonly Column[]>;
+    /** 开启持久化时必需的命名空间。 */
+    columnsKey?: MaybeRefOrGetter<string | undefined>;
+    /** 是否开启偏好持久化。 */
+    persistent?: MaybeRefOrGetter<boolean>;
+    /** 随每份偏好快照写入的版本。 */
+    schemaVersion?: number;
+    /** 可选的本地或服务端 storage 实现。 */
+    storage?: VTableColumnPreferenceStorage;
+    /** 列宽和拖拽持久化的防抖时长。 */
+    writeDelay?: number;
+    /** 有效列变化时调用。 */
+    onColumnsChange?: (columns: readonly Column[]) => void;
+    /** 一次本地偏好操作完成后调用。 */
+    onPreferencesChange?: (snapshot: VTableColumnPreferenceSnapshot) => void;
+    /** 读取、写入或删除偏好失败时调用。 */
+    onError?: (error: Error) => void;
+}
+/** 创建可扩展且可防持久化竞态的列偏好 feature。 */
+export declare function useColumnPreferences<Column extends VTablePreferenceColumn<Column>>(options: UseColumnPreferencesOptions<Column>): VTableColumnPreferences<Column>;

package/dist/components/tt-vtable/src/features/column-preferences/useColumnPreferences.js

@@ -0,0 +1,232 @@
+import "axios";
+import "element-plus";
+import { isDef as X, isError as Y, isNumber as Z, isClient as S } from "../../../../../packages/utils/src/is.js";
+import { shallowRef as p, computed as O, watch as V, toValue as h, onScopeDispose as _ } 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 { createLocalColumnPreferenceStorage as $ } from "./column-preference-storage.js";
+function ee(r) {
+  return new Error(Y(r) ? String(r).replace(/^Error:\s*/, "") : String(r));
+}
+function N(r) {
+  const o = /* @__PURE__ */ new Map();
+  function n(i) {
+    i.forEach((s, a) => {
+      var v;
+      const f = {
+        key: s.key,
+        visible: s.visible !== !1,
+        order: a
+      };
+      Z(s.width) && s.width > 0 && (f.width = s.width), s.frozen && (f.frozen = s.frozen), o.set(s.key, f), (v = s.columns) != null && v.length && n(s.columns);
+    });
+  }
+  return n(r), o;
+}
+function F(r, o) {
+  const n = N(r);
+  return n.forEach((i, s) => {
+    const a = o.get(s);
+    a && n.set(s, { ...i, ...a, key: s });
+  }), n;
+}
+function re(r, o) {
+  return { schemaVersion: o, columns: [...r.values()].map((n) => ({ ...n })) };
+}
+function ne(r) {
+  return new Map(r.columns.map((o) => [o.key, { ...o }]));
+}
+function q(r, o) {
+  var n;
+  if (r.some((i) => i.key === o)) return r.map((i) => i.key);
+  for (const i of r) {
+    if (!((n = i.columns) != null && n.length)) continue;
+    const s = q(i.columns, o);
+    if (s) return s;
+  }
+}
+function L(r, o) {
+  return [...r].sort((n, i) => {
+    var f, v;
+    const s = ((f = o.get(n.key)) == null ? void 0 : f.order) ?? 0, a = ((v = o.get(i.key)) == null ? void 0 : v.order) ?? 0;
+    return s - a;
+  }).filter((n) => {
+    var i;
+    return ((i = o.get(n.key)) == null ? void 0 : i.visible) !== !1;
+  }).map((n) => {
+    var f;
+    const i = o.get(n.key), s = (f = n.columns) != null && f.length ? L(n.columns, o) : void 0;
+    return {
+      ...n,
+      visible: !0,
+      ...i != null && i.width ? { width: i.width } : {},
+      ...X(i == null ? void 0 : i.frozen) ? { frozen: i.frozen } : {},
+      ...s ? { columns: s } : {}
+    };
+  });
+}
+function Pe(r) {
+  const o = p([]), n = p(/* @__PURE__ */ new Map()), i = p(!1), s = p(), a = r.storage ?? $(), f = r.schemaVersion ?? 1, v = Math.max(0, r.writeDelay ?? 180);
+  let d = 0, w = 0, l;
+  const M = O(() => L(o.value, n.value)), W = O(() => {
+    const e = [];
+    function t(c, u) {
+      c.forEach((m) => {
+        var g;
+        const y = n.value.get(m.key) ?? {
+          key: m.key,
+          visible: m.visible !== !1,
+          order: 0
+        };
+        e.push({ ...y, column: m, depth: u }), (g = m.columns) != null && g.length && t(m.columns, u + 1);
+      });
+    }
+    return t(o.value, 0), e;
+  });
+  function b() {
+    return h(r.columnsKey) || void 0;
+  }
+  function E(e) {
+    var c;
+    const t = ee(e);
+    s.value = t, (c = r.onError) == null || c.call(r, t);
+  }
+  function P() {
+    var e;
+    (e = r.onColumnsChange) == null || e.call(r, M.value);
+  }
+  function K() {
+    return re(n.value, f);
+  }
+  async function z() {
+    if (!h(r.persistent ?? !1)) return;
+    const e = b();
+    if (e)
+      try {
+        await a.write(e, K());
+      } catch (t) {
+        E(t);
+      }
+  }
+  function A() {
+    if (!S) {
+      z();
+      return;
+    }
+    l && window.clearTimeout(l), l = window.setTimeout(() => {
+      l = void 0, z();
+    }, v);
+  }
+  function x(e) {
+    var c;
+    w += 1, n.value = e;
+    const t = K();
+    P(), (c = r.onPreferencesChange) == null || c.call(r, t), A();
+  }
+  function k(e, t) {
+    o.value = [...e], n.value = F(o.value, n.value), t && (w += 1), P();
+  }
+  function I(e) {
+    k(e, !0);
+  }
+  function C(e, t) {
+    const c = n.value.get(e);
+    if (!c) return;
+    const u = new Map(n.value);
+    u.set(e, { ...c, ...t, key: e }), x(u);
+  }
+  function j(e) {
+    C(e, { visible: !0 });
+  }
+  function B(e) {
+    C(e, { visible: !1 });
+  }
+  function G(e, t) {
+    const c = q(o.value, e);
+    if (!c) return;
+    const u = c.indexOf(e);
+    if (u < 0) return;
+    const m = Number.isFinite(t) ? Math.max(0, Math.min(Math.floor(t), c.length - 1)) : u;
+    if (u === m) return;
+    const y = [...c];
+    y.splice(u, 1), y.splice(m, 0, e);
+    const g = new Map(n.value);
+    y.forEach((D, U) => {
+      const R = g.get(D);
+      R && g.set(D, { ...R, order: U });
+    }), x(g);
+  }
+  function H(e, t) {
+    !Number.isFinite(t) || t <= 0 || C(e, { width: t });
+  }
+  function J(e, t) {
+    C(e, { frozen: t ?? !1 });
+  }
+  async function T() {
+    if (!h(r.persistent ?? !1)) return;
+    const e = b();
+    if (!e) return;
+    d += 1;
+    const t = d, c = w;
+    i.value = !0, s.value = void 0;
+    try {
+      const u = await a.read(e);
+      if (t !== d || c !== w || !u || u.schemaVersion !== f) return;
+      n.value = F(o.value, ne(u)), P();
+    } catch (u) {
+      t === d && E(u);
+    } finally {
+      t === d && (i.value = !1);
+    }
+  }
+  async function Q() {
+    var t;
+    w += 1, d += 1, l && S && window.clearTimeout(l), l = void 0, n.value = N(o.value), s.value = void 0, P(), (t = r.onPreferencesChange) == null || t.call(r, K());
+    const e = b();
+    if (!(!e || !h(r.persistent ?? !1)))
+      try {
+        await a.remove(e);
+      } catch (c) {
+        E(c);
+      }
+  }
+  return V(
+    () => h(r.columns),
+    (e) => k(e, !1),
+    { immediate: !0 }
+  ), V(
+    [() => h(r.persistent ?? !1), () => h(r.columnsKey)],
+    ([e]) => {
+      e && T();
+    },
+    { immediate: !0 }
+  ), _(() => {
+    d += 1, l && S && window.clearTimeout(l);
+  }), {
+    sourceColumns: o,
+    columns: M,
+    entries: W,
+    isLoading: i,
+    error: s,
+    replaceAll: I,
+    show: j,
+    hide: B,
+    move: G,
+    setWidth: H,
+    setFrozen: J,
+    load: T,
+    resetPreferences: Q
+  };
+}
+export {
+  Pe as useColumnPreferences
+};

package/dist/components/tt-vtable/src/features/editing/useCellEditing.d.ts

@@ -0,0 +1,48 @@
+import { ComputedRef, Ref } from 'vue';
+import { TtVTableEditingCell, TtVTableFieldPath, TtVTableRowKey } from '../../public/table-api';
+import { TtVTableEditCommit } from '../../public/table-events';
+import { TtVTableEditValidator } from '../../public/table-props';
+/** 暴露给 runtime 的编辑状态与动作。 */
+export interface VTableCellEditing<Key extends TtVTableRowKey> {
+    /** 当前单元格；未编辑时为 undefined。 */
+    activeCell: Readonly<Ref<Readonly<TtVTableEditingCell<Key>> | undefined>>;
+    /** 当前单元格是否正在校验。 */
+    isValidating: Readonly<Ref<boolean>>;
+    /** 当前校验错误。 */
+    validationError: Readonly<Ref<Error | undefined>>;
+    /** 是否存在活动编辑器。 */
+    isEditing: ComputedRef<boolean>;
+    /** 开始编辑单元格。 */
+    start: (rowKey: Key, field: TtVTableFieldPath) => Promise<void>;
+    /** 更新草稿且不修改 runtime 记录。 */
+    setValue: (value: unknown) => void;
+    /** 校验并提交当前草稿。 */
+    commit: (value?: unknown) => Promise<boolean>;
+    /** 取消当前编辑。 */
+    cancel: () => void;
+    /** 仅校验当前草稿且不提交。 */
+    validate: (value?: unknown) => Promise<boolean>;
+    /** 组件销毁时释放编辑器状态。 */
+    release: () => void;
+}
+/** 单元格编辑 feature 所需依赖。 */
+export interface UseCellEditingOptions<Row extends Record<string, unknown>, Key extends TtVTableRowKey> {
+    /** 按主键读取一条 runtime 记录。 */
+    getRecordByKey: (key: Key) => Row | undefined;
+    /** 从 runtime 记录读取字段值。 */
+    getFieldValue: (record: Row, field: TtVTableFieldPath) => unknown;
+    /** 通过 records feature 提交一个单元格。 */
+    setCellValue: (key: Key, field: TtVTableFieldPath, value: unknown, source: "editing") => Promise<void> | void;
+    /** 读取字段配置的校验函数。 */
+    getValidator?: (field: TtVTableFieldPath) => TtVTableEditValidator<Row, Key> | undefined;
+    /** 捕获状态后打开原生或 Vue 编辑器。 */
+    startNativeEditing?: (key: Key, field: TtVTableFieldPath) => Promise<void> | void;
+    /** 关闭原生或 Vue 编辑器。 */
+    cancelNativeEditing?: () => void;
+    /** 编辑提交成功后调用一次。 */
+    onCommit?: (change: TtVTableEditCommit<Key>) => void;
+    /** 校验或提交失败时调用。 */
+    onError?: (error: Error) => void;
+}
+/** 创建草稿隔离且可防异步校验竞态的编辑 feature。 */
+export declare function useCellEditing<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey>(options: UseCellEditingOptions<Row, Key>): VTableCellEditing<Key>;

package/dist/components/tt-vtable/src/features/editing/useCellEditing.js

@@ -0,0 +1,102 @@
+import "axios";
+import "element-plus";
+import { isError as B } from "../../../../../packages/utils/src/is.js";
+import { shallowRef as g, computed as F } 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 o(e, a) {
+  return !!e && !!a && e.rowKey === a.rowKey && e.field === a.field;
+}
+function N(e) {
+  if (e === !1) return new Error("Cell validation failed.");
+  if (!(e === !0 || !e))
+    return new Error(e);
+}
+function S(e) {
+  return new Error(B(e) ? String(e).replace(/^Error:\s*/, "") : String(e));
+}
+function P(e) {
+  const a = g(), d = g(!1), u = g();
+  let n = 0;
+  const K = F(() => !!a.value);
+  async function x(l, c) {
+    var i;
+    const r = e.getRecordByKey(l);
+    if (!r) throw new Error(`Cannot edit missing record "${String(l)}".`);
+    const t = e.getFieldValue(r, c);
+    n += 1, u.value = void 0, a.value = { rowKey: l, field: c, previousValue: t, value: t }, await ((i = e.startNativeEditing) == null ? void 0 : i.call(e, l, c));
+  }
+  function w(l) {
+    a.value && (a.value = { ...a.value, value: l });
+  }
+  async function y(l = ((c) => (c = a.value) == null ? void 0 : c.value)()) {
+    var m, V, h;
+    const r = a.value;
+    if (!r) return !1;
+    const t = e.getRecordByKey(r.rowKey);
+    if (!t) return !1;
+    const i = (m = e.getValidator) == null ? void 0 : m.call(e, r.field);
+    if (!i)
+      return u.value = void 0, !0;
+    n += 1;
+    const f = n;
+    d.value = !0, u.value = void 0;
+    try {
+      const E = await i({
+        record: t,
+        rowKey: r.rowKey,
+        field: r.field,
+        previousValue: r.previousValue,
+        value: l
+      });
+      if (f !== n || !o(r, a.value)) return !1;
+      const v = N(E);
+      return u.value = v, v && ((V = e.onError) == null || V.call(e, v)), !v;
+    } catch (E) {
+      const v = S(E);
+      return f !== n || !o(r, a.value) || (u.value = v, (h = e.onError) == null || h.call(e, v)), !1;
+    } finally {
+      f === n && (d.value = !1);
+    }
+  }
+  async function C(l = ((c) => (c = a.value) == null ? void 0 : c.value)()) {
+    var t, i;
+    const r = a.value;
+    if (!r || d.value || (w(l), !await y(l) || !o(r, a.value))) return !1;
+    try {
+      if (await e.setCellValue(r.rowKey, r.field, l, "editing"), !o(r, a.value)) return !1;
+      const f = {
+        rowKey: r.rowKey,
+        field: r.field,
+        previousValue: r.previousValue,
+        value: l,
+        changedFields: [r.field],
+        source: "editing"
+      };
+      return a.value = void 0, u.value = void 0, (t = e.onCommit) == null || t.call(e, f), !0;
+    } catch (f) {
+      const m = S(f);
+      return u.value = m, (i = e.onError) == null || i.call(e, m), !1;
+    }
+  }
+  function s() {
+    var l;
+    n += 1, d.value = !1, u.value = void 0, a.value = void 0, (l = e.cancelNativeEditing) == null || l.call(e);
+  }
+  function q() {
+    s();
+  }
+  return { activeCell: a, isValidating: d, validationError: u, isEditing: K, start: x, setValue: w, commit: C, cancel: s, validate: y, release: q };
+}
+export {
+  P as useCellEditing
+};

package/dist/components/tt-vtable/src/features/form-integration/useVTableForm.d.ts

@@ -0,0 +1,51 @@
+import { Ref } from 'vue';
+import { TtExtendedFormApi, TtFormProps } from '../../../../tt-form';
+import { TtVTableApi, TtVTableRowKey } from '../../public/table-api';
+import { TtVTableProps } from '../../public/table-props';
+/** TtVTableForm 的组合属性。 */
+export interface TtVTableFormProps<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey, FormValues extends Record<string, unknown> = Record<string, unknown>> {
+    /** TtForm 配置。 */
+    form: TtFormProps<FormValues>;
+    /** TtVTable 配置。 */
+    table: TtVTableProps<Row, Key, FormValues>;
+}
+/** TtVTableForm 仅组合 form 与 table 两个命名空间。 */
+export interface TtVTableFormApi<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 稳定 TtForm API。 */
+    form: TtExtendedFormApi;
+    /** 稳定 TtVTable API。 */
+    table: TtVTableApi<Row, Key>;
+}
+/** 表单查询状态写入策略。 */
+export interface VTableFormQueryStrategy {
+    /** 是否把分页恢复为初始状态。 */
+    resetPagination: boolean;
+    /** 是否同时清理排序和筛选。 */
+    resetSortAndFilters: boolean;
+}
+/** 表单与表格联动 feature 所需依赖。 */
+export interface UseVTableFormOptions<FormValues extends Record<string, unknown>> {
+    /** 初始查询参数根快照。 */
+    initialQueryParams?: Readonly<Partial<FormValues>>;
+    /** 原子写入查询参数及对应重置策略。 */
+    applyQueryState: (queryParams: Readonly<Partial<FormValues>>, strategy: VTableFormQueryStrategy) => void;
+    /** 使用当前查询状态发起远程请求。 */
+    fetchRecords: () => Promise<boolean>;
+    /** 表单提交并准备查询前调用。 */
+    onSubmit?: (values: Readonly<FormValues>) => Promise<void> | void;
+    /** 表单重置并准备查询前调用。 */
+    onReset?: (values: Readonly<FormValues>) => Promise<void> | void;
+}
+/** 表单与表格联动状态及动作。 */
+export interface VTableFormIntegration<FormValues extends Record<string, unknown>> {
+    /** 当前不可变查询参数根快照。 */
+    queryParams: Readonly<Ref<Readonly<Partial<FormValues>>>>;
+    /** 是否正在执行提交或重置查询。 */
+    isSubmitting: Readonly<Ref<boolean>>;
+    /** 提交表单并执行一次查询。 */
+    submit: (values: FormValues) => Promise<boolean>;
+    /** 重置表单状态并执行一次查询。 */
+    reset: (values: FormValues) => Promise<boolean>;
+}
+/** 创建表单提交、重置与表格查询之间的单向联动。 */
+export declare function useVTableForm<FormValues extends Record<string, unknown>>(options: UseVTableFormOptions<FormValues>): VTableFormIntegration<FormValues>;

package/dist/components/tt-vtable/src/features/pagination/useTablePagination.d.ts

@@ -0,0 +1,40 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
+import { TtVTablePageChange } from '../../public/table-events';
+/** 暴露给 runtime 的分页状态与动作。 */
+export interface VTablePagination<Row> {
+    /** 当前从 1 开始的页码。 */
+    page: Readonly<Ref<number>>;
+    /** 每页记录数。 */
+    pageSize: Readonly<Ref<number>>;
+    /** 记录总数。 */
+    total: ComputedRef<number>;
+    /** 总页数。 */
+    pageCount: ComputedRef<number>;
+    /** 当前本地页记录，远程模式下为已加载记录。 */
+    pageRecords: ComputedRef<readonly Row[]>;
+    /** 修改当前页码。 */
+    setPage: (page: number) => void;
+    /** 修改每页数量并回到第一页。 */
+    setPageSize: (pageSize: number) => void;
+    /** 恢复配置的初始分页状态。 */
+    reset: () => void;
+    /** 接收最近一次有效远程响应的总数。 */
+    setRemoteTotal: (total: number) => void;
+    /** records 或 total 变化后校正页码。 */
+    reconcilePage: () => void;
+}
+/** 分页 feature 所需依赖。 */
+export interface UseTablePaginationOptions<Row> {
+    /** 初始从 1 开始的页码。 */
+    initialPage?: number;
+    /** 初始每页记录数。 */
+    initialPageSize?: number;
+    /** 是否使用远程记录源。 */
+    isRemote: MaybeRefOrGetter<boolean>;
+    /** 读取 runtime 当前加载的记录。 */
+    getRecords: () => readonly Row[];
+    /** 每次语义分页变化调用一次。 */
+    onChange?: (change: TtVTablePageChange) => Promise<void> | void;
+}
+/** 创建单一状态源的本地或远程分页。 */
+export declare function useTablePagination<Row>(options: UseTablePaginationOptions<Row>): VTablePagination<Row>;

package/dist/components/tt-vtable/src/features/pagination/useTablePagination.js

@@ -0,0 +1,51 @@
+import { shallowRef as f, computed as s, toValue as h, watch as S } from "vue";
+function r(e, i) {
+  return !Number.isFinite(e) || e <= 0 ? i : Math.max(1, Math.floor(e));
+}
+function x(e) {
+  return !Number.isFinite(e) || e <= 0 ? 0 : Math.floor(e);
+}
+function b(e) {
+  const i = r(e.initialPage ?? 1, 1), o = r(e.initialPageSize ?? 20, 20), a = f(i), n = f(o), m = f(0), c = s(() => h(e.isRemote) ? m.value : e.getRecords().length), l = s(() => Math.max(1, Math.ceil(c.value / n.value))), P = s(() => {
+    const u = e.getRecords();
+    if (h(e.isRemote)) return u;
+    const t = (a.value - 1) * n.value;
+    return u.slice(t, t + n.value);
+  });
+  function g(u) {
+    var t;
+    (t = e.onChange) == null || t.call(e, { page: a.value, pageSize: n.value, reason: u });
+  }
+  function d(u) {
+    const t = Math.min(r(u, a.value), l.value);
+    t !== a.value && (a.value = t, g("page"));
+  }
+  function z(u) {
+    const t = r(u, n.value);
+    t === n.value && a.value === 1 || (n.value = t, a.value = 1, g("page-size"));
+  }
+  function R() {
+    a.value === i && n.value === o || (a.value = i, n.value = o, g("reset"));
+  }
+  function M(u) {
+    m.value = x(u), v();
+  }
+  function v() {
+    a.value <= l.value || (a.value = l.value);
+  }
+  return S(c, v), {
+    page: a,
+    pageSize: n,
+    total: c,
+    pageCount: l,
+    pageRecords: P,
+    setPage: d,
+    setPageSize: z,
+    reset: R,
+    setRemoteTotal: M,
+    reconcilePage: v
+  };
+}
+export {
+  b as useTablePagination
+};