@nokecy/qc-ui-components 0.0.0-stage → 2.0.0-beta.1

package/dist/esm/array-table/errorLocator.js

@@ -0,0 +1,95 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it.return != null) it.return(); } finally { if (didErr) throw err; } } }; }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+/** ArrayTable 的一列：AG-Grid 列 id 与它承载的内层数据字段名（Column key 与字段名可能不同，如设计器形态）。 */
+
+/**
+ * 提交校验失败时 ArrayTable 的错误定位器（注册到 adapters 的 form-error-focus，见 registerErrorLocator）。
+ *
+ * 错误格可能不在 DOM 里（行被虚拟化、懒挂载格卸回了文本），按 DOM 找不到，所以按 Formily 的错误列表定位：
+ * 取表内最靠前的（先行后列，行按当前显示顺序、列按当前列序），ensureIndexVisible / ensureColumnVisible 滚到位，
+ * 再激活该格并聚焦输入。@author nokecy
+ */
+export var createArrayTableErrorLocator = function createArrayTableErrorLocator(deps) {
+  return function (form, root) {
+    var _api$isDestroyed, _api$getAllDisplayedC, _api$getAllDisplayedC2, _first$feedback$messa, _first$feedback$addre;
+    var field = deps.field;
+    var container = deps.getContainer();
+    var api = deps.getApi();
+    if (!container || !api || (_api$isDestroyed = api.isDestroyed) !== null && _api$isDestroyed !== void 0 && _api$isDestroyed.call(api) || field.form !== form || !root.contains(container)) return undefined;
+    var rows = Array.isArray(field.value) ? field.value : [];
+    var baseLength = field.path.length;
+    var displayed = ((_api$getAllDisplayedC = (_api$getAllDisplayedC2 = api.getAllDisplayedColumns) === null || _api$getAllDisplayedC2 === void 0 ? void 0 : _api$getAllDisplayedC2.call(api)) !== null && _api$getAllDisplayedC !== void 0 ? _api$getAllDisplayedC : []).map(function (c) {
+      return c.getColId();
+    });
+    var columns = deps.getColumns();
+    var candidates = [];
+    var _iterator = _createForOfIteratorHelper(form.queryFeedbacks({
+        type: 'error',
+        address: "".concat(field.address.toString(), ".*")
+      })),
+      _step;
+    try {
+      var _loop = function _loop() {
+          var _feedback$path, _feedback$address, _columns$find, _api$getRowNode;
+          var feedback = _step.value;
+          var segments = String((_feedback$path = feedback.path) !== null && _feedback$path !== void 0 ? _feedback$path : '').split('.');
+          var dataIndex = Number(segments[baseLength]);
+          var row = rows[dataIndex];
+          if (!Number.isInteger(dataIndex) || row == null || _typeof(row) !== 'object') return 0; // continue
+          var dataName = segments.slice(baseLength + 1).join('.');
+          // 地址里含 Column 的 void 段（`items.2.column1.qty`），先按内层字段名匹配，其次按 Column key。
+          var addressSegments = String((_feedback$address = feedback.address) !== null && _feedback$address !== void 0 ? _feedback$address : '').split('.');
+          var column = (_columns$find = columns.find(function (c) {
+            return c.dataName === dataName;
+          })) !== null && _columns$find !== void 0 ? _columns$find : columns.find(function (c) {
+            return addressSegments.includes(c.colId);
+          });
+          if (!column) return 0; // continue
+          var node = (_api$getRowNode = api.getRowNode) === null || _api$getRowNode === void 0 ? void 0 : _api$getRowNode.call(api, deps.getRowId(row));
+          var rowIndex = node === null || node === void 0 ? void 0 : node.rowIndex;
+          // 行被过滤掉了（不在显示列表里）无法定位。
+          if (typeof rowIndex !== 'number') return 0; // continue
+          var colOrder = displayed.indexOf(column.colId);
+          candidates.push({
+            rowOrder: rowIndex,
+            colOrder: colOrder < 0 ? Number.MAX_SAFE_INTEGER : colOrder,
+            rowIndex: rowIndex,
+            colId: column.colId,
+            feedback: feedback,
+            title: column.title
+          });
+        },
+        _ret;
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        _ret = _loop();
+        if (_ret === 0) continue;
+      }
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
+    }
+    if (candidates.length === 0) return undefined;
+    candidates.sort(function (a, b) {
+      return a.rowOrder - b.rowOrder || a.colOrder - b.colOrder;
+    });
+    var first = candidates[0];
+    var reason = (_first$feedback$messa = first.feedback.messages) === null || _first$feedback$messa === void 0 ? void 0 : _first$feedback$messa[0];
+    var location = {
+      container: container,
+      addressPrefix: field.address.toString(),
+      address: (_first$feedback$addre = first.feedback.address) === null || _first$feedback$addre === void 0 ? void 0 : _first$feedback$addre.toString(),
+      title: first.title,
+      reason: typeof reason === 'string' ? reason : undefined,
+      reveal: function reveal() {
+        return deps.focus({
+          rowIndex: first.rowIndex,
+          colId: first.colId
+        });
+      }
+    };
+    return location;
+  };
+};

package/dist/esm/array-table/fixedGuard.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 列 `fixed` 别名的宽度保护。
+ *
+ * `fixed`(antd Table 写法)会映射成 AG-Grid 的 pinned。schema 里写了很多 fixed 的表(几列固定在左、操作列固定在右),
+ * 在窄屏上固定列自己就占满可视宽度,中间区域没有空间、无法横向滚动。保护的做法:固定列总宽超过
+ * 可视宽度的 `fixedColumnsMaxRatio`(默认 0.5)时,取消「由 fixed 推导出来」的固定列,表格变宽后再恢复。
+ * 开发者显式写的 `pinned`、默认序号列等不受影响(但它们的宽度计入占用)。
+ *
+ * 取消顺序:左固定组从最靠内侧(最右)的列开始逐列取消;右固定(通常是操作列)优先保留,
+ * 仅靠取消左固定仍超阈值时,才从右固定组最靠内侧(最左)的列开始取消。
+ *
+ * 本文件是纯计算,不依赖 AG-Grid 运行时;index.tsx 用 onGridSizeChanged / onColumnResized 等事件调用并用
+ * applyColumnState 应用结果。
+ *
+ * @author nokecy
+ */
+import type { ColDef } from 'ag-grid-community';
+export type PinnedSide = 'left' | 'right';
+/** 默认阈值:固定列总宽最多占可视宽度的一半 */
+export declare const DEFAULT_FIXED_COLUMNS_MAX_RATIO = 0.5;
+/** 记下列的固定来自 fixed 别名;side 为空时不做事。返回传入的 colDef。 */
+export declare const markFixedDerived: <T extends object>(colDef: T, side: PinnedSide | undefined) => T;
+/** 取列定义上记录的 fixed 推导固定侧 */
+export declare const getFixedDerivedSide: (colDef: ColDef | object) => PinnedSide | undefined;
+export interface GuardColumn {
+    colId: string;
+    width: number;
+    /** 有效固定侧(包含「保护取消了、原本该固定」的列),未固定为 null */
+    pinned: PinnedSide | null | undefined;
+    /** 固定是否来自 fixed 别名(只有它们能被取消) */
+    derived?: boolean;
+}
+/** 固定列(左+右)总宽 / 可视宽度 */
+export declare const pinnedWidthRatio: (columns: GuardColumn[], viewportWidth: number) => number;
+/**
+ * 给定列(按显示顺序)、可视宽度与阈值,返回应取消固定的列 id(按取消顺序)。
+ */
+export declare const planFixedRelease: (columns: GuardColumn[], viewportWidth: number, maxRatio?: number) => string[];
+/** 来自 AG-Grid getColumnState() 的最小子集 */
+export interface ColumnStateLite {
+    colId: string;
+    width?: number;
+    pinned?: PinnedSide | boolean | null;
+    hide?: boolean | null;
+}
+export interface ReconcileInput {
+    /** 按显示顺序的列状态 */
+    state: ColumnStateLite[];
+    /** 由 fixed 别名推导固定的列 -> 固定侧 */
+    derivedSides: Record<string, PinnedSide>;
+    /** 已被保护取消固定的列 */
+    released: ReadonlySet<string>;
+    viewportWidth: number;
+    maxRatio?: number;
+}
+export interface ReconcileResult {
+    /** 需要应用到 AG-Grid 的固定状态变更;空数组表示无需调用 API */
+    changes: Array<{
+        colId: string;
+        pinned: PinnedSide | null;
+    }>;
+    /** 应用后被保护取消固定的列 */
+    released: Set<string>;
+    /** 本次新取消固定的列(用于开发环境告警) */
+    newlyReleased: string[];
+    /** 计算时固定列总宽 / 可视宽度 */
+    ratio: number;
+}
+/**
+ * 对照当前列状态重新计算哪些推导固定列该取消、哪些该恢复。
+ *
+ * 与用户手动操作的取舍:
+ *  - 用户把推导列手动取消固定(不在 released 里却已是未固定):尊重,不恢复;
+ *  - 用户把推导列改固定到另一侧,或把被保护取消的列重新固定:视为显式 pinned,此后不再受保护(宽度仍计入占用);
+ *  - 用户拖拽列宽无法与窗口变化区分,宽度保护始终按当前实际列宽计算。
+ */
+export declare const reconcileFixedColumns: (input: ReconcileInput) => ReconcileResult;

package/dist/esm/array-table/fixedGuard.js

@@ -0,0 +1,202 @@
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it.return != null) it.return(); } finally { if (didErr) throw err; } } }; }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+/**
+ * 列 `fixed` 别名的宽度保护。
+ *
+ * `fixed`(antd Table 写法)会映射成 AG-Grid 的 pinned。schema 里写了很多 fixed 的表(几列固定在左、操作列固定在右),
+ * 在窄屏上固定列自己就占满可视宽度,中间区域没有空间、无法横向滚动。保护的做法:固定列总宽超过
+ * 可视宽度的 `fixedColumnsMaxRatio`(默认 0.5)时,取消「由 fixed 推导出来」的固定列,表格变宽后再恢复。
+ * 开发者显式写的 `pinned`、默认序号列等不受影响(但它们的宽度计入占用)。
+ *
+ * 取消顺序:左固定组从最靠内侧(最右)的列开始逐列取消;右固定(通常是操作列)优先保留,
+ * 仅靠取消左固定仍超阈值时,才从右固定组最靠内侧(最左)的列开始取消。
+ *
+ * 本文件是纯计算,不依赖 AG-Grid 运行时;index.tsx 用 onGridSizeChanged / onColumnResized 等事件调用并用
+ * applyColumnState 应用结果。
+ *
+ * @author nokecy
+ */
+
+/** 默认阈值:固定列总宽最多占可视宽度的一半 */
+export var DEFAULT_FIXED_COLUMNS_MAX_RATIO = 0.5;
+
+/** 列定义 -> 由 fixed 别名推导出的固定侧(显式写了 pinned 的列不记录)。不往 colDef 上塞自定义字段。 */
+var derivedSideOf = new WeakMap();
+
+/** 记下列的固定来自 fixed 别名;side 为空时不做事。返回传入的 colDef。 */
+export var markFixedDerived = function markFixedDerived(colDef, side) {
+  if (side) derivedSideOf.set(colDef, side);
+  return colDef;
+};
+
+/** 取列定义上记录的 fixed 推导固定侧 */
+export var getFixedDerivedSide = function getFixedDerivedSide(colDef) {
+  return derivedSideOf.get(colDef);
+};
+/** 保护是否关闭:阈值无效、>=1 或 Infinity */
+var isGuardOff = function isGuardOff(maxRatio, viewportWidth) {
+  return !Number.isFinite(maxRatio) || maxRatio >= 1 || maxRatio < 0 || !(viewportWidth > 0);
+};
+
+/** 固定列(左+右)总宽 / 可视宽度 */
+export var pinnedWidthRatio = function pinnedWidthRatio(columns, viewportWidth) {
+  return viewportWidth > 0 ? columns.reduce(function (sum, c) {
+    return c.pinned ? sum + (c.width || 0) : sum;
+  }, 0) / viewportWidth : 0;
+};
+
+/**
+ * 给定列(按显示顺序)、可视宽度与阈值,返回应取消固定的列 id(按取消顺序)。
+ */
+export var planFixedRelease = function planFixedRelease(columns, viewportWidth) {
+  var maxRatio = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : DEFAULT_FIXED_COLUMNS_MAX_RATIO;
+  if (isGuardOff(maxRatio, viewportWidth)) return [];
+  var limit = viewportWidth * maxRatio;
+  var total = columns.reduce(function (sum, c) {
+    return c.pinned ? sum + (c.width || 0) : sum;
+  }, 0);
+  if (total <= limit) return [];
+  var released = [];
+  var release = function release(c) {
+    released.push(c.colId);
+    total -= c.width || 0;
+  };
+  var lefts = columns.filter(function (c) {
+    return c.pinned === 'left' && c.derived;
+  }).reverse(); // 最靠内侧(最右)在前
+  var _iterator = _createForOfIteratorHelper(lefts),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var c = _step.value;
+      if (total <= limit) return released;
+      release(c);
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  var rights = columns.filter(function (c) {
+    return c.pinned === 'right' && c.derived;
+  }); // 最靠内侧(最左)在前
+  var _iterator2 = _createForOfIteratorHelper(rights),
+    _step2;
+  try {
+    for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+      var _c = _step2.value;
+      if (total <= limit) return released;
+      release(_c);
+    }
+  } catch (err) {
+    _iterator2.e(err);
+  } finally {
+    _iterator2.f();
+  }
+  return released;
+};
+
+/** 来自 AG-Grid getColumnState() 的最小子集 */
+
+var normalizePinned = function normalizePinned(pinned) {
+  return pinned === 'left' || pinned === true ? 'left' : pinned === 'right' ? 'right' : null;
+};
+
+/**
+ * 对照当前列状态重新计算哪些推导固定列该取消、哪些该恢复。
+ *
+ * 与用户手动操作的取舍:
+ *  - 用户把推导列手动取消固定(不在 released 里却已是未固定):尊重,不恢复;
+ *  - 用户把推导列改固定到另一侧,或把被保护取消的列重新固定:视为显式 pinned,此后不再受保护(宽度仍计入占用);
+ *  - 用户拖拽列宽无法与窗口变化区分,宽度保护始终按当前实际列宽计算。
+ */
+export var reconcileFixedColumns = function reconcileFixedColumns(input) {
+  var state = input.state,
+    derivedSides = input.derivedSides,
+    viewportWidth = input.viewportWidth,
+    _input$maxRatio = input.maxRatio,
+    maxRatio = _input$maxRatio === void 0 ? DEFAULT_FIXED_COLUMNS_MAX_RATIO : _input$maxRatio;
+  var released = new Set(input.released);
+  var entries = [];
+  var candidates = new Map();
+  var _iterator3 = _createForOfIteratorHelper(state),
+    _step3;
+  try {
+    for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+      var _s$width;
+      var s = _step3.value;
+      if (s.hide) continue; // 隐藏的列不占宽度,released 状态保持
+      var cur = normalizePinned(s.pinned);
+      var side = derivedSides[s.colId];
+      var width = (_s$width = s.width) !== null && _s$width !== void 0 ? _s$width : 0;
+      if (side && cur === side && !released.has(s.colId)) {
+        candidates.set(s.colId, {
+          current: cur,
+          side: side
+        });
+        entries.push({
+          colId: s.colId,
+          width: width,
+          pinned: side,
+          derived: true
+        });
+      } else if (side && cur === null && released.has(s.colId)) {
+        candidates.set(s.colId, {
+          current: null,
+          side: side
+        });
+        entries.push({
+          colId: s.colId,
+          width: width,
+          pinned: side,
+          derived: true
+        });
+      } else {
+        if (cur !== null) released.delete(s.colId); // 用户重新固定/换边:当作显式 pinned
+        entries.push({
+          colId: s.colId,
+          width: width,
+          pinned: cur,
+          derived: false
+        });
+      }
+    }
+  } catch (err) {
+    _iterator3.e(err);
+  } finally {
+    _iterator3.f();
+  }
+  var ratio = pinnedWidthRatio(entries, viewportWidth);
+  var toRelease = new Set(planFixedRelease(entries, viewportWidth, maxRatio));
+  var changes = [];
+  var newlyReleased = [];
+  Array.from(candidates).forEach(function (_ref) {
+    var _ref2 = _slicedToArray(_ref, 2),
+      colId = _ref2[0],
+      _ref2$ = _ref2[1],
+      current = _ref2$.current,
+      side = _ref2$.side;
+    var desired = toRelease.has(colId) ? null : side;
+    if (desired === null) {
+      if (!input.released.has(colId)) newlyReleased.push(colId);
+      released.add(colId);
+    } else {
+      released.delete(colId);
+    }
+    if (current !== desired) changes.push({
+      colId: colId,
+      pinned: desired
+    });
+  });
+  return {
+    changes: changes,
+    released: released,
+    newlyReleased: newlyReleased,
+    ratio: ratio
+  };
+};

package/dist/esm/array-table/hooks.d.ts

@@ -0,0 +1,94 @@
+import { RefObject } from 'react';
+import { GridApi } from 'ag-grid-community';
+import { ArrayField } from '@nokecy/formily-core';
+type CellFocusRequest = {
+    isCurrent: () => boolean;
+    schedule: (callback: () => void, delay: number) => void;
+};
+type BeginCellFocusRequest = (resolveCell: () => Element | null | undefined, isTargetCurrent?: () => boolean) => CellFocusRequest;
+/** 单元格聚焦；已获得焦点的控件保留用户光标，等待挂载的请求可被新操作取消。@author nokecy */
+export type CellFocusSource = 'keyboard' | 'pointer' | 'pointer-activated';
+/**
+ * @param options.openDateOnKeyboard 键盘到达日期格时是否自动展开面板，默认 false：与演示一致——
+ *   鼠标点击由 antd 自己展开，键盘到达保持收起、直接键入覆盖。传 true 才在键盘落焦那一次展开。
+ */
+export declare const useCellFocus: (options?: {
+    openDateOnKeyboard?: boolean | undefined;
+}) => {
+    focusInputInCell: (cell: Element, isTargetCurrent?: () => boolean, source?: CellFocusSource) => void;
+    scheduleCellFocus: (resolveCell: () => Element | null | undefined, delay: number, isTargetCurrent?: () => boolean, source?: CellFocusSource) => void;
+    beginFocusRequest: BeginCellFocusRequest;
+};
+/**
+ * 键盘导航 Hook
+ * 处理方向键在表格单元格间的导航
+ */
+export declare const useKeyboardNavigation: (ref: RefObject<any>, dataSource: any[], focusInputInCell: (cell: Element, isTargetCurrent?: () => boolean, source?: CellFocusSource) => void, activateCell?: ((api: GridApi, node: any, colId: string) => boolean) | undefined, beginSharedFocusRequest?: BeginCellFocusRequest, isTabFocusDeferred?: () => boolean) => {
+    handleCellKeyDown: (event: any) => void;
+};
+/**
+ * 行拖拽 Hook
+ * 处理行拖拽排序逻辑
+ */
+export declare const useRowDrag: (field: ArrayField) => {
+    handleRowDragMove: (event: any) => void;
+};
+/**
+ * 这个按键该不该交给单元格里的输入框自己处理(浏览器原生行为),而不是当成表格的快捷键/单元格导航。
+ *
+ * AG-Grid 把 Ctrl+A 当成「选中所有单元格」、Home/End 当成「跳到行首/行尾单元格」并 preventDefault;
+ * 我们的 handleCellKeyDown 又把方向键一律当成「跳到相邻单元格」——输入框里全选、用方向键移动光标、
+ * Shift+方向键扩选文字就全都做不了。规则:
+ *  - Ctrl/Cmd+A、Home/End、带 Shift/Ctrl/Alt/Cmd 的方向键、输入法组字期间的按键 -> 输入框自己处理;
+ *  - 左右方向键:光标还能动就移动光标(有选区时先收起选区),已经在最左/最右再按才跳到相邻单元格;
+ *  - 上下方向键:单行输入框没有纵向光标,照旧在行间导航;多行文本域在首行/末行才导航;
+ *  - 焦点不在输入框里(在单元格本身)、只读输入框(如下拉选择)、不支持光标的输入框:照旧导航。
+ * 复制/粘贴/剪切/撤销 AG-Grid 本来就没拦,不必处理。@author nokecy
+ */
+export declare const isNativeInputKey: (event: KeyboardEvent) => boolean;
+/** AG-Grid 的 suppressKeyboardEvent:让 AG-Grid 不再拦截输入框自己处理的按键,并记下这次按键的判定 */
+export declare const suppressNativeInputKeys: ({ event }: {
+    event: KeyboardEvent;
+}) => boolean;
+type GridCellFocusParams = {
+    api: GridApi;
+    root: RefObject<HTMLElement | null | undefined>;
+    rowIndex: number;
+    colId: string;
+    beginFocusRequest: BeginCellFocusRequest;
+    focusInputInCell: (cell: Element, isTargetCurrent?: () => boolean, source?: CellFocusSource) => void;
+    activateCell?: (api: GridApi, node: any, colId: string) => boolean;
+    /** 列不在可视区时也滚到可见（横向滚动），错误定位用 */
+    ensureColumnVisible?: boolean;
+};
+/**
+ * 行已在行模型里：滚到可见、设焦点格、必要时激活懒挂载格，等格子渲染出来后把焦点落进输入控件。
+ * 行进入模型后 DOM 还要再渲染一拍（懒挂载格还要挂载），所以分多次轮询，直到格子出现；
+ * 返回的 Promise 在落焦完成（返回获得焦点的控件）、或请求被用户操作取消 / 超时（返回 undefined）时结束。@author nokecy
+ */
+export declare const focusGridCell: (params: GridCellFocusParams) => Promise<HTMLElement | undefined>;
+export type PendingAddedRowFocus = {
+    rowId: string;
+    colId: string;
+};
+/**
+ * 新增行进入 AG-Grid 行模型之后，把焦点落到它的首个可编辑格。
+ *
+ * 新行是 field.push 之后经 React 重渲、rowData 更新才进入行模型的，push 当下 getDisplayedRowAtIndex 还取不到它，
+ * 所以由 onRowDataUpdated 调用本函数；行模型里还没有该行时返回 false，调用方保留待办等下一次。@author nokecy
+ */
+export declare const focusAddedRow: (params: Omit<GridCellFocusParams, "colId" | "rowIndex"> & {
+    pending: PendingAddedRowFocus;
+}) => boolean;
+/**
+ * AG-Grid `tabToNextCell`：跳过序号列/勾选列；末行末格再按 Tab 时，传了 `onTabPastEnd` 就由它新增一行并落焦，
+ * 否则保持默认（焦点离开表格）。返回值语义见 AG-Grid：位置=去那格，true=留在原格，false=交浏览器。@author nokecy
+ */
+export declare const createTabToNextCell: (onTabPastEnd?: () => void) => (params: any) => any;
+/**
+ * Esc 放弃本格修改（规范 §7.6.3）：Formily 受控值是实时写入的，没有「进入时的值」，
+ * 所以在输入框获得焦点时记下当时的文本，Esc 时用原生 setter + input 事件写回，值照常经 Formily 回流。
+ * 下拉/日期等自带 Esc 语义的控件不处理。@author nokecy
+ */
+export declare const useCellEscapeRevert: (ref: RefObject<HTMLElement | null | undefined>) => void;
+export {};