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

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

@@ -0,0 +1,101 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createArrayTableErrorLocator = void 0;
+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
+ */
+var createArrayTableErrorLocator = exports.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/cjs/array-table/hooks.d.ts

@@ -7,16 +7,23 @@ type CellFocusRequest = {
 };
 type BeginCellFocusRequest = (resolveCell: () => Element | null | undefined, isTargetCurrent?: () => boolean) => CellFocusRequest;
 /** 单元格聚焦；已获得焦点的控件保留用户光标，等待挂载的请求可被新操作取消。@author nokecy */
-export declare const useCellFocus: () => {
-    focusInputInCell: (cell: Element, isTargetCurrent?: () => boolean) => void;
-    scheduleCellFocus: (resolveCell: () => Element | null | undefined, delay: number, isTargetCurrent?: () => boolean) => void;
+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) => void, activateCell?: ((api: GridApi, node: any, colId: string) => boolean) | undefined, beginSharedFocusRequest?: BeginCellFocusRequest) => {
+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;
 };
 /**
@@ -43,4 +50,45 @@ export declare const isNativeInputKey: (event: KeyboardEvent) => boolean;
 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 {};

package/dist/cjs/array-table/hooks.js

@@ -1,10 +1,20 @@
 "use strict";
 
+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); }
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.useRowDrag = exports.useKeyboardNavigation = exports.useCellFocus = exports.suppressNativeInputKeys = exports.isNativeInputKey = void 0;
+exports.useRowDrag = exports.useKeyboardNavigation = exports.useCellFocus = exports.useCellEscapeRevert = exports.suppressNativeInputKeys = exports.isNativeInputKey = exports.focusGridCell = exports.focusAddedRow = exports.createTabToNextCell = void 0;
 var _react = require("react");
+var _indexColumn = require("./indexColumn");
+var _excluded = ["pending"];
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _objectWithoutProperties(source, excluded) { if (source == null) return {}; var target = _objectWithoutPropertiesLoose(source, excluded); var key, i; if (Object.getOwnPropertySymbols) { var sourceSymbolKeys = Object.getOwnPropertySymbols(source); for (i = 0; i < sourceSymbolKeys.length; i++) { key = sourceSymbolKeys[i]; if (excluded.indexOf(key) >= 0) continue; if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue; target[key] = source[key]; } } return target; }
+function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }
 // setSelectionRange 仅 textarea 与 text/search/url/tel/password 类型 input 支持;
 // checkbox/number/date 等调用会抛 InvalidStateError,故用白名单守卫。@author nokecy
 var supportsSelectionRange = function supportsSelectionRange(el) {
@@ -72,13 +82,43 @@ var useCellFocusRequests = function useCellFocusRequests() {
 };
 
 /** 单元格聚焦；已获得焦点的控件保留用户光标，等待挂载的请求可被新操作取消。@author nokecy */
+
+/**
+ * 鼠标点击刚把懒挂载格挂成真控件后，补一次展开。
+ * 点击落在纯文本上，控件是点击之后才挂载的，antd 根本没收到这次点击，所以要自己补：
+ * Select 在 mousedown 上切换展开（已展开则不动，避免补成关闭），DatePicker 在 click 上展开。@author nokecy
+ */
+var openFreshlyMountedControl = function openFreshlyMountedControl(input) {
+  if (input.closest('.ant-picker')) {
+    input.click();
+    return;
+  }
+  var select = input.closest('.ant-select');
+  if (select && !select.classList.contains('ant-select-open')) {
+    input.dispatchEvent(new MouseEvent('mousedown', {
+      bubbles: true,
+      cancelable: true
+    }));
+  }
+};
+
+/**
+ * @param options.openDateOnKeyboard 键盘到达日期格时是否自动展开面板，默认 false：与演示一致——
+ *   鼠标点击由 antd 自己展开，键盘到达保持收起、直接键入覆盖。传 true 才在键盘落焦那一次展开。
+ */
 var useCellFocus = exports.useCellFocus = function useCellFocus() {
+  var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
   var beginFocusRequest = useCellFocusRequests();
+  var openDateOnKeyboard = options.openDateOnKeyboard === true;
+  var openDateRef = (0, _react.useRef)(openDateOnKeyboard);
+  openDateRef.current = openDateOnKeyboard;
+  /** source 是一次性的来源提示，只作用于这一次落焦；鼠标来源与已聚焦的格不会触发展开。 */
   var focusInputInCell = (0, _react.useCallback)(function (cell) {
     var _ref, _cell$querySelector;
     var isTargetCurrent = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : function () {
       return true;
     };
+    var source = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 'pointer';
     var row = cell.closest('.ag-row');
     var rowId = row === null || row === void 0 ? void 0 : row.getAttribute('row-id');
     var rowIndex = row === null || row === void 0 ? void 0 : row.getAttribute('row-index');
@@ -93,10 +133,15 @@ var useCellFocus = exports.useCellFocus = function useCellFocus() {
       if (!(element !== null && element !== void 0 && element.isConnected) || !cell.contains(element) || !request.isCurrent()) return;
       if (document.activeElement === element) return;
       element.focus();
-      // 同步设置首次进入的光标，避免延迟任务覆盖用户随后选择的文字。@author nokecy
+      // 懒挂载格的鼠标点击落在纯文本上，antd 没收到点击，挂载后补展开一次（只在刚挂载的那一次，
+      // 已聚焦的格在上面直接返回，再点不会重复触发）；键盘到达保持收起，openDateOnKeyboard 才在日期格展开。
+      if (document.activeElement === element) {
+        if (source === 'pointer-activated') openFreshlyMountedControl(element);else if (source === 'keyboard' && openDateRef.current && element.closest('.ant-picker')) element.click();
+      }
+      // 首次进入全选（规范 §7.6.3：键入即覆盖，不是追加）；同步设置，避免延迟任务覆盖用户随后选择的文字。
+      // 已聚焦的输入框在上面直接返回，所以用户点出来的光标/选区不会被改动。@author nokecy
       if (document.activeElement === element && element.matches('input, textarea') && supportsSelectionRange(element)) {
-        var input = element;
-        input.setSelectionRange(input.value.length, input.value.length);
+        element.select();
       }
     };
     var active = document.activeElement;
@@ -121,11 +166,11 @@ var useCellFocus = exports.useCellFocus = function useCellFocus() {
     }
     focusElement((_ref = (_cell$querySelector = cell.querySelector(selector)) !== null && _cell$querySelector !== void 0 ? _cell$querySelector : cell.querySelector('input:not([disabled]), textarea:not([disabled]), [contenteditable="true"], [tabindex]:not([disabled])')) !== null && _ref !== void 0 ? _ref : cell);
   }, [beginFocusRequest]);
-  var scheduleCellFocus = (0, _react.useCallback)(function (resolveCell, delay, isTargetCurrent) {
+  var scheduleCellFocus = (0, _react.useCallback)(function (resolveCell, delay, isTargetCurrent, source) {
     var request = beginFocusRequest(resolveCell, isTargetCurrent);
     request.schedule(function () {
       var cell = resolveCell();
-      if (cell !== null && cell !== void 0 && cell.isConnected) focusInputInCell(cell, isTargetCurrent);
+      if (cell !== null && cell !== void 0 && cell.isConnected) focusInputInCell(cell, isTargetCurrent, source);
     }, delay);
   }, [beginFocusRequest, focusInputInCell]);
   return {
@@ -139,7 +184,7 @@ var useCellFocus = exports.useCellFocus = function useCellFocus() {
  * 键盘导航 Hook
  * 处理方向键在表格单元格间的导航
  */
-var useKeyboardNavigation = exports.useKeyboardNavigation = function useKeyboardNavigation(ref, dataSource, focusInputInCell, activateCell, beginSharedFocusRequest) {
+var useKeyboardNavigation = exports.useKeyboardNavigation = function useKeyboardNavigation(ref, dataSource, focusInputInCell, activateCell, beginSharedFocusRequest, isTabFocusDeferred) {
   var beginLocalFocusRequest = useCellFocusRequests(!beginSharedFocusRequest);
   var beginFocusRequest = beginSharedFocusRequest !== null && beginSharedFocusRequest !== void 0 ? beginSharedFocusRequest : beginLocalFocusRequest;
   var handleCellKeyDown = (0, _react.useCallback)(function (event) {
@@ -153,6 +198,31 @@ var useKeyboardNavigation = exports.useKeyboardNavigation = function useKeyboard
     // 判定用 keydown 当时记下的(见 suppressNativeInputKeys);没记过(不是 AG-Grid 触发的)才现算。
     if ((_nativeKeyDecisions$g = nativeKeyDecisions.get(keyEvent)) !== null && _nativeKeyDecisions$g !== void 0 ? _nativeKeyDecisions$g : isNativeInputKey(keyEvent)) return;
 
+    // Tab / Enter 由 AG-Grid 自己换格，但它只聚焦单元格 div，输入框拿不到焦点、键入无效：
+    // 等 AG-Grid 换完格再把焦点落进新格的输入框（并全选）。方向键走下面自己的导航。@author nokecy
+    if ((keyEvent.key === 'Tab' || keyEvent.key === 'Enter') && !keyEvent.ctrlKey && !keyEvent.altKey && !keyEvent.metaKey) {
+      if (keyEvent.key === 'Tab' && isTabFocusDeferred !== null && isTabFocusDeferred !== void 0 && isTabFocusDeferred()) return;
+      var resolveFocused = function resolveFocused() {
+        var _api$getFocusedCell, _ref$current$querySel, _ref$current;
+        var focused = (_api$getFocusedCell = api.getFocusedCell) === null || _api$getFocusedCell === void 0 ? void 0 : _api$getFocusedCell.call(api);
+        if (!focused) return null;
+        return (_ref$current$querySel = (_ref$current = ref.current) === null || _ref$current === void 0 ? void 0 : _ref$current.querySelector(".ag-row[row-index=\"".concat(focused.rowIndex, "\"] .ag-cell[col-id=\"").concat(focused.column.getColId(), "\"]"))) !== null && _ref$current$querySel !== void 0 ? _ref$current$querySel : null;
+      };
+      var request = beginFocusRequest(resolveFocused);
+      request.schedule(function () {
+        var _api$getFocusedCell2, _api$getDisplayedRowA;
+        // 懒挂载格先激活挂树，再给挂载留出时间。
+        var focused = (_api$getFocusedCell2 = api.getFocusedCell) === null || _api$getFocusedCell2 === void 0 ? void 0 : _api$getFocusedCell2.call(api);
+        var focusedNode = focused ? (_api$getDisplayedRowA = api.getDisplayedRowAtIndex) === null || _api$getDisplayedRowA === void 0 ? void 0 : _api$getDisplayedRowA.call(api, focused.rowIndex) : undefined;
+        var justActivated = !!(activateCell && focused && focusedNode && activateCell(api, focusedNode, focused.column.getColId()));
+        request.schedule(function () {
+          var cell = resolveFocused();
+          if (cell !== null && cell !== void 0 && cell.isConnected) focusInputInCell(cell, undefined, 'keyboard');
+        }, justActivated ? 150 : 10);
+      }, 10);
+      return;
+    }
+
     // 处理上下左右键导航
     if (keyEvent.key === 'ArrowDown' || keyEvent.key === 'ArrowUp' || keyEvent.key === 'ArrowLeft' || keyEvent.key === 'ArrowRight') {
       var currentRowIndex = node.rowIndex;
@@ -194,17 +264,17 @@ var useKeyboardNavigation = exports.useKeyboardNavigation = function useKeyboard
       // 检查目标位置是否有效
       var isValidTarget = keyEvent.key === 'ArrowLeft' || keyEvent.key === 'ArrowRight' || targetRowIndex >= 0 && targetRowIndex < dataSource.length;
       if (isValidTarget) {
-        var _api$getDisplayedRowA;
-        var targetNode = (_api$getDisplayedRowA = api.getDisplayedRowAtIndex) === null || _api$getDisplayedRowA === void 0 ? void 0 : _api$getDisplayedRowA.call(api, targetRowIndex);
+        var _api$getDisplayedRowA2;
+        var targetNode = (_api$getDisplayedRowA2 = api.getDisplayedRowAtIndex) === null || _api$getDisplayedRowA2 === void 0 ? void 0 : _api$getDisplayedRowA2.call(api, targetRowIndex);
         var navigated = false;
         var resolveTarget = function resolveTarget() {
-          var _ref$current;
-          return (_ref$current = ref.current) === null || _ref$current === void 0 ? void 0 : _ref$current.querySelector(".ag-row[row-index=\"".concat(targetRowIndex, "\"] .ag-cell[col-id=\"").concat(targetColId, "\"]"));
+          var _ref$current2;
+          return (_ref$current2 = ref.current) === null || _ref$current2 === void 0 ? void 0 : _ref$current2.querySelector(".ag-row[row-index=\"".concat(targetRowIndex, "\"] .ag-cell[col-id=\"").concat(targetColId, "\"]"));
         };
         var _isTargetCurrent = function _isTargetCurrent() {
-          var _ref$current2, _api$isDestroyed, _api$getDisplayedRowA2;
-          if (!((_ref$current2 = ref.current) !== null && _ref$current2 !== void 0 && _ref$current2.isConnected) || (_api$isDestroyed = api.isDestroyed) !== null && _api$isDestroyed !== void 0 && _api$isDestroyed.call(api)) return false;
-          if (targetNode && ((_api$getDisplayedRowA2 = api.getDisplayedRowAtIndex) === null || _api$getDisplayedRowA2 === void 0 ? void 0 : _api$getDisplayedRowA2.call(api, targetRowIndex)) !== targetNode) return false;
+          var _ref$current3, _api$isDestroyed, _api$getDisplayedRowA3;
+          if (!((_ref$current3 = ref.current) !== null && _ref$current3 !== void 0 && _ref$current3.isConnected) || (_api$isDestroyed = api.isDestroyed) !== null && _api$isDestroyed !== void 0 && _api$isDestroyed.call(api)) return false;
+          if (targetNode && ((_api$getDisplayedRowA3 = api.getDisplayedRowAtIndex) === null || _api$getDisplayedRowA3 === void 0 ? void 0 : _api$getDisplayedRowA3.call(api, targetRowIndex)) !== targetNode) return false;
           if (navigated && api.getFocusedCell) {
             var _focused$column;
             var focused = api.getFocusedCell();
@@ -212,9 +282,9 @@ var useKeyboardNavigation = exports.useKeyboardNavigation = function useKeyboard
           }
           return true;
         };
-        var request = beginFocusRequest(resolveTarget, _isTargetCurrent);
+        var _request = beginFocusRequest(resolveTarget, _isTargetCurrent);
         // 延迟执行以确保当前编辑完成
-        request.schedule(function () {
+        _request.schedule(function () {
           api.setFocusedCell(targetRowIndex, targetColId);
           navigated = true;
 
@@ -226,10 +296,10 @@ var useKeyboardNavigation = exports.useKeyboardNavigation = function useKeyboard
           // 不使用原生startEditingCell,而是手动触发编辑状态
           // v33 themeQuartz 容器不再有 .ag-theme-alpine 类;且行虚拟化下 DOM 顺序与 rowIndex 不一致,
           // 改为直接在 ref 容器内按 row-index + col-id 属性定位目标单元格 @author nokecy
-          request.schedule(function () {
+          _request.schedule(function () {
             var targetCell = resolveTarget();
             if (targetCell !== null && targetCell !== void 0 && targetCell.isConnected) {
-              focusInputInCell(targetCell, _isTargetCurrent);
+              focusInputInCell(targetCell, _isTargetCurrent, 'keyboard');
             }
           }, 150);
         }, 10);
@@ -293,6 +363,8 @@ var isNativeInputKey = exports.isNativeInputKey = function isNativeInputKey(even
   var key = event.key;
   if (event.isComposing) return true;
   if ((event.ctrlKey || event.metaKey) && key.toLowerCase() === 'a') return true;
+  // 复制/剪切/粘贴交给输入框的原生行为：AG-Grid 不应拦走单元格内输入框的 Ctrl/Cmd+C/X/V（允许粘贴，规范 §11）。
+  if ((event.ctrlKey || event.metaKey) && !event.altKey && ['c', 'x', 'v'].includes(key.toLowerCase())) return true;
   if (key === 'Home' || key === 'End') return true;
   if (!key.startsWith('Arrow')) return false;
   if (event.shiftKey || event.ctrlKey || event.altKey || event.metaKey) return true;
@@ -323,4 +395,165 @@ var suppressNativeInputKeys = exports.suppressNativeInputKeys = function suppres
   var native = isNativeInputKey(event);
   nativeKeyDecisions.set(event, native);
   return native;
+};
+/**
+ * 行已在行模型里：滚到可见、设焦点格、必要时激活懒挂载格，等格子渲染出来后把焦点落进输入控件。
+ * 行进入模型后 DOM 还要再渲染一拍（懒挂载格还要挂载），所以分多次轮询，直到格子出现；
+ * 返回的 Promise 在落焦完成（返回获得焦点的控件）、或请求被用户操作取消 / 超时（返回 undefined）时结束。@author nokecy
+ */
+var focusGridCell = exports.focusGridCell = function focusGridCell(params) {
+  var _api$getDisplayedRowA4, _api$isDestroyed2, _api$ensureIndexVisib, _api$ensureColumnVisi;
+  var api = params.api,
+    root = params.root,
+    rowIndex = params.rowIndex,
+    colId = params.colId,
+    beginFocusRequest = params.beginFocusRequest,
+    focusInputInCell = params.focusInputInCell,
+    activateCell = params.activateCell;
+  var node = (_api$getDisplayedRowA4 = api.getDisplayedRowAtIndex) === null || _api$getDisplayedRowA4 === void 0 ? void 0 : _api$getDisplayedRowA4.call(api, rowIndex);
+  if (!node || (_api$isDestroyed2 = api.isDestroyed) !== null && _api$isDestroyed2 !== void 0 && _api$isDestroyed2.call(api)) return Promise.resolve(undefined);
+  var resolveCell = function resolveCell() {
+    var _root$current;
+    return (_root$current = root.current) === null || _root$current === void 0 ? void 0 : _root$current.querySelector(".ag-row[row-index=\"".concat(rowIndex, "\"] .ag-cell[col-id=\"").concat(colId, "\"]"));
+  };
+  var isTargetCurrent = function isTargetCurrent() {
+    var _root$current2, _api$isDestroyed3, _api$getFocusedCell3;
+    if (!((_root$current2 = root.current) !== null && _root$current2 !== void 0 && _root$current2.isConnected) || (_api$isDestroyed3 = api.isDestroyed) !== null && _api$isDestroyed3 !== void 0 && _api$isDestroyed3.call(api)) return false;
+    var focused = (_api$getFocusedCell3 = api.getFocusedCell) === null || _api$getFocusedCell3 === void 0 ? void 0 : _api$getFocusedCell3.call(api);
+    return !focused || focused.rowIndex === rowIndex && focused.column.getColId() === colId;
+  };
+  var request = beginFocusRequest(resolveCell, isTargetCurrent);
+  (_api$ensureIndexVisib = api.ensureIndexVisible) === null || _api$ensureIndexVisib === void 0 || _api$ensureIndexVisib.call(api, rowIndex);
+  if (params.ensureColumnVisible) (_api$ensureColumnVisi = api.ensureColumnVisible) === null || _api$ensureColumnVisi === void 0 || _api$ensureColumnVisi.call(api, colId);
+  api.setFocusedCell(rowIndex, colId);
+  var activated = activateCell ? activateCell(api, node, colId) : false;
+  return new Promise(function (resolve) {
+    var attempt = function attempt(remaining) {
+      if (!request.isCurrent()) return resolve(undefined);
+      var cell = resolveCell();
+      if (cell !== null && cell !== void 0 && cell.isConnected) {
+        focusInputInCell(cell, isTargetCurrent, 'keyboard');
+        var active = document.activeElement;
+        return resolve(active instanceof HTMLElement && cell.contains(active) ? active : undefined);
+      }
+      if (remaining <= 0) return resolve(undefined);
+      setTimeout(function () {
+        return attempt(remaining - 1);
+      }, 50);
+    };
+    setTimeout(function () {
+      return attempt(8);
+    }, activated ? 150 : 30);
+  });
+};
+
+// 按行 id 记录：排序时新行的显示行号与数据下标不一致，落焦必须取行节点的显示行号。
+
+/**
+ * 新增行进入 AG-Grid 行模型之后，把焦点落到它的首个可编辑格。
+ *
+ * 新行是 field.push 之后经 React 重渲、rowData 更新才进入行模型的，push 当下 getDisplayedRowAtIndex 还取不到它，
+ * 所以由 onRowDataUpdated 调用本函数；行模型里还没有该行时返回 false，调用方保留待办等下一次。@author nokecy
+ */
+var focusAddedRow = exports.focusAddedRow = function focusAddedRow(params) {
+  var _rest$api$isDestroyed, _rest$api, _rest$api$getRowNode, _rest$api2;
+  var pending = params.pending,
+    rest = _objectWithoutProperties(params, _excluded);
+  if ((_rest$api$isDestroyed = (_rest$api = rest.api).isDestroyed) !== null && _rest$api$isDestroyed !== void 0 && _rest$api$isDestroyed.call(_rest$api)) return true;
+  var rowIndex = (_rest$api$getRowNode = (_rest$api2 = rest.api).getRowNode) === null || _rest$api$getRowNode === void 0 || (_rest$api$getRowNode = _rest$api$getRowNode.call(_rest$api2, pending.rowId)) === null || _rest$api$getRowNode === void 0 ? void 0 : _rest$api$getRowNode.rowIndex;
+  if (typeof rowIndex !== 'number') return false;
+  void focusGridCell(_objectSpread(_objectSpread({}, rest), {}, {
+    rowIndex: rowIndex,
+    colId: pending.colId
+  }));
+  return true;
+};
+
+/** 不应被 Tab 停留的列：默认序号列与勾选列（规范 §7.6.3：Tab 只在可编辑格之间移动）。@author nokecy */
+var isTabSkippedColumn = function isTabSkippedColumn(colId) {
+  return colId === _indexColumn.ARRAY_TABLE_INDEX_FIELD || colId === 'ag-Grid-SelectionColumn';
+};
+
+/**
+ * AG-Grid `tabToNextCell`：跳过序号列/勾选列；末行末格再按 Tab 时，传了 `onTabPastEnd` 就由它新增一行并落焦，
+ * 否则保持默认（焦点离开表格）。返回值语义见 AG-Grid：位置=去那格，true=留在原格，false=交浏览器。@author nokecy
+ */
+var createTabToNextCell = exports.createTabToNextCell = function createTabToNextCell(onTabPastEnd) {
+  return function (params) {
+    var _params$api$getAllDis, _params$api$getAllDis2, _params$api, _params$api$getDispla, _params$api$getDispla2, _params$api2;
+    var columns = (_params$api$getAllDis = (_params$api$getAllDis2 = (_params$api = params.api).getAllDisplayedColumns) === null || _params$api$getAllDis2 === void 0 ? void 0 : _params$api$getAllDis2.call(_params$api)) !== null && _params$api$getAllDis !== void 0 ? _params$api$getAllDis : [];
+    var step = params.backwards ? -1 : 1;
+    var rowCount = (_params$api$getDispla = (_params$api$getDispla2 = (_params$api2 = params.api).getDisplayedRowCount) === null || _params$api$getDispla2 === void 0 ? void 0 : _params$api$getDispla2.call(_params$api2)) !== null && _params$api$getDispla !== void 0 ? _params$api$getDispla : 0;
+    var next = params.nextCellPosition;
+    var prev = params.previousCellPosition;
+    // AG-Grid 在行首/行尾会折到相邻行；统一在这里按列序重新找下一个可停留的格。
+    if (next && isTabSkippedColumn(next.column.getColId())) {
+      var rowIndex = next.rowIndex;
+      var colIndex = columns.indexOf(next.column) + step;
+      for (;;) {
+        if (colIndex < 0 || colIndex >= columns.length) {
+          rowIndex += step;
+          if (rowIndex < 0 || rowIndex >= rowCount) {
+            next = null;
+            break;
+          }
+          colIndex = step > 0 ? 0 : columns.length - 1;
+          continue;
+        }
+        if (!isTabSkippedColumn(columns[colIndex].getColId())) {
+          next = _objectSpread(_objectSpread({}, next), {}, {
+            rowIndex: rowIndex,
+            column: columns[colIndex]
+          });
+          break;
+        }
+        colIndex += step;
+      }
+    }
+    if (next) return next;
+    // 没有下一格：前进方向且正处在最后一格 -> 新增行
+    if (!params.backwards && onTabPastEnd && prev && prev.rowIndex === rowCount - 1) {
+      onTabPastEnd();
+      return true;
+    }
+    return false;
+  };
+};
+
+/**
+ * Esc 放弃本格修改（规范 §7.6.3）：Formily 受控值是实时写入的，没有「进入时的值」，
+ * 所以在输入框获得焦点时记下当时的文本，Esc 时用原生 setter + input 事件写回，值照常经 Formily 回流。
+ * 下拉/日期等自带 Esc 语义的控件不处理。@author nokecy
+ */
+var useCellEscapeRevert = exports.useCellEscapeRevert = function useCellEscapeRevert(ref) {
+  (0, _react.useEffect)(function () {
+    var root = ref.current;
+    if (!root) return;
+    var snapshots = new WeakMap();
+    var isPlainInput = function isPlainInput(el) {
+      return el instanceof HTMLInputElement && !el.readOnly && !el.disabled && !el.closest('.ant-select, .ant-picker') && /^(text|search|url|tel|number)$/i.test(el.type || 'text');
+    };
+    var onFocusIn = function onFocusIn(event) {
+      if (isPlainInput(event.target)) snapshots.set(event.target, event.target.value);
+    };
+    var onKeyDown = function onKeyDown(event) {
+      var _Object$getOwnPropert;
+      if (event.key !== 'Escape' || event.isComposing || !isPlainInput(event.target)) return;
+      var snapshot = snapshots.get(event.target);
+      if (snapshot === undefined || snapshot === event.target.value) return;
+      var setter = (_Object$getOwnPropert = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')) === null || _Object$getOwnPropert === void 0 ? void 0 : _Object$getOwnPropert.set;
+      setter === null || setter === void 0 || setter.call(event.target, snapshot);
+      event.target.dispatchEvent(new Event('input', {
+        bubbles: true
+      }));
+      event.target.select();
+      event.stopPropagation();
+    };
+    root.addEventListener('focusin', onFocusIn);
+    root.addEventListener('keydown', onKeyDown, true);
+    return function () {
+      root.removeEventListener('focusin', onFocusIn);
+      root.removeEventListener('keydown', onKeyDown, true);
+    };
+  }, [ref]);
 };

package/dist/cjs/array-table/index.d.ts

@@ -2,12 +2,18 @@ import React from "react";
 import { AgGridReactProps } from "ag-grid-react";
 declare const _default: React.ForwardRefExoticComponent<Partial<AgGridReactProps<any> & {
     height?: string | number | undefined;
+    minRows?: number | undefined;
+    maxRows?: number | undefined;
     gridKey: string;
+    title?: React.ReactNode;
     onRowDrag?: boolean | undefined;
     disabled?: boolean | undefined;
     batchRemove?: boolean | undefined;
     onRemove?: ((index: number) => void) | undefined;
     fixedColumnsMaxRatio?: number | undefined;
+    tabAddsRow?: boolean | undefined;
+    openDateOnKeyboard?: boolean | undefined;
+    summary?: import("./summary").ArrayTableSummary | undefined;
 } & {
     children?: React.ReactNode;
 }> & React.RefAttributes<any>>;