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

package/dist/esm/ag-grid-plus/utils/valueEnumColor.js

@@ -20,19 +20,23 @@ function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e
  *
  * @author nokecy
  */
+import { STATUS_PILL } from "./statusPill";
 import { contrastRatio, darkenUntilContrast, lightenUntilContrast, relativeLuminance } from "../../shared/contrast";
 
 /** antd Tag 语义档名。 */
 
 var WHITE = '#ffffff';
 
-/** 语义档名 → 表格文字色（白底实测 ≥4.5:1）。 */
+/**
+ * 语义档名 → 表格文字色，取状态胶囊六态的文字色（statusPill.ts，对各自底色 ≥4.5:1，白底同样达标），
+ * 没配 `status` 的枚举与配了 `status` 的列在同一页上色值一致（DESIGN.md §3.2）。
+ */
 export var semanticTextColors = {
-  default: '#595959',
-  processing: '#0958d9',
-  success: '#237804',
-  warning: '#ad4e00',
-  error: '#cf1322'
+  default: STATUS_PILL.wait.fg,
+  processing: STATUS_PILL.running.fg,
+  success: STATUS_PILL.done.fg,
+  warning: STATUS_PILL.warning.fg,
+  error: STATUS_PILL.alarm.fg
 };
 
 /** antd Tag 预设名 / 常见 CSS 色名 → 起始 hex，再交给对比度压色。 */
@@ -62,8 +66,8 @@ var parseHex = function parseHex(color) {
 };
 
 /** 底色是否为深色表面。 */
-var isDarkSurface = function isDarkSurface(background) {
-  return relativeLuminance(background) < 0.18;
+export var isDarkSurface = function isDarkSurface(background) {
+  return !!background && !!parseHex(background) && relativeLuminance(background) < 0.18;
 };
 
 /**

package/dist/esm/ag-grid-plus/utils/valueFormat.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 表格数据格式出厂默认（DESIGN.md §7.7）：数字千分位、空值 `—`；页面自己写 valueFormatter 即覆盖。
+ * @author nokecy
+ */
+export declare const EMPTY_PLACEHOLDER = "\u2014";
+/** 空值统一为 `—`；0 是有效值，原样保留。 */
+export declare const isEmptyValue: (value: unknown) => boolean;
+/**
+ * 千分位，只动整数部分，小数位原样保留（字符串数值不经过浮点，不丢精度）。
+ * 不是纯数字的值（科学计数法、带单位的文本）原样返回。
+ */
+export declare function formatThousands(value: unknown): string;
+/** 只补空值占位。 */
+export declare function formatEmpty(value: unknown): string;
+/**
+ * 给没有自己 valueFormatter 的叶子列补默认格式。已有 valueFormatter、枚举列、日期/布尔列类型一律不动。
+ * @param inferredNumber 该列由首行数据推断为数值
+ */
+export declare function withDefaultValueFormat<T extends Record<string, any>>(col: T, inferredNumber: boolean): T;

package/dist/esm/ag-grid-plus/utils/valueFormat.js

@@ -0,0 +1,63 @@
+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 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); }
+/**
+ * 表格数据格式出厂默认（DESIGN.md §7.7）：数字千分位、空值 `—`；页面自己写 valueFormatter 即覆盖。
+ * @author nokecy
+ */
+
+export var EMPTY_PLACEHOLDER = '—';
+var PLAIN_NUMBER = /^(-?)(\d+)(\.\d+)?$/;
+
+/** 空值统一为 `—`；0 是有效值，原样保留。 */
+export var isEmptyValue = function isEmptyValue(value) {
+  return value === null || value === undefined || value === '';
+};
+
+/**
+ * 千分位，只动整数部分，小数位原样保留（字符串数值不经过浮点，不丢精度）。
+ * 不是纯数字的值（科学计数法、带单位的文本）原样返回。
+ */
+export function formatThousands(value) {
+  var _m$;
+  if (isEmptyValue(value)) return EMPTY_PLACEHOLDER;
+  var text = String(value).trim();
+  var m = PLAIN_NUMBER.exec(text);
+  if (!m) return String(value);
+  return "".concat(m[1]).concat(m[2].replace(/\B(?=(\d{3})+(?!\d))/g, ',')).concat((_m$ = m[3]) !== null && _m$ !== void 0 ? _m$ : '');
+}
+
+/** 只补空值占位。 */
+export function formatEmpty(value) {
+  return isEmptyValue(value) ? EMPTY_PLACEHOLDER : String(value);
+}
+
+/** 字段名像编码、年份、序号的数值列不加千分位（订单号、年份加逗号是错的）。 */
+var IDENTIFIER_LIKE = /(?:^|[a-z])(?:id|code|no|number|year|seq|sequence|sort|order|index)$/i;
+var EXPLICIT_NUMERIC = new Set(['numericColumn', 'numberColumn']);
+var SKIP_TYPES = new Set(['dateColumn', 'dateTimeColumn', 'bool']);
+
+/**
+ * 给没有自己 valueFormatter 的叶子列补默认格式。已有 valueFormatter、枚举列、日期/布尔列类型一律不动。
+ * @param inferredNumber 该列由首行数据推断为数值
+ */
+export function withDefaultValueFormat(col, inferredNumber) {
+  var _col$field;
+  if (col.valueFormatter || col.valueEnum) return col;
+  var types = (Array.isArray(col.type) ? col.type : [col.type]).filter(Boolean).map(String);
+  if (types.some(function (t) {
+    return SKIP_TYPES.has(t);
+  })) return col;
+  var field = String((_col$field = col.field) !== null && _col$field !== void 0 ? _col$field : '');
+  var numeric = types.some(function (t) {
+    return EXPLICIT_NUMERIC.has(t);
+  }) || inferredNumber && !IDENTIFIER_LIKE.test(field);
+  return _objectSpread(_objectSpread({}, col), {}, {
+    valueFormatter: function valueFormatter(p) {
+      return numeric ? formatThousands(p.value) : formatEmpty(p.value);
+    }
+  });
+}

package/dist/esm/ag-grid-plus/utils.js

@@ -198,10 +198,11 @@ var convertSortModel = function convertSortModel(sortModel) {
   return sorter;
 };
 var dateValueFormatter = function dateValueFormatter(params) {
-  return params.value ? dayjs(params.value).format("YYYY-MM-DD") : "";
+  return params.value ? dayjs(params.value).format("YYYY-MM-DD") : "—";
 };
 var dateTimeValueFormatter = function dateTimeValueFormatter(params) {
-  return params.value ? dayjs(params.value).format("YYYY-MM-DD HH:mm:ss") : "";
+  // 列表到分钟，日志与审计到秒由页面自己传 valueFormatter（DESIGN.md §7.7）
+  return params.value ? dayjs(params.value).format("YYYY-MM-DD HH:mm") : "—";
 };
 
 //@ts-ignore

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

@@ -1,3 +1,4 @@
 import React from "react";
+export declare const getDefaultValue: (defaultValue: any, schema: any) => any;
 declare const ArrayAddBtn: (props: any) => React.JSX.Element | null;
 export default ArrayAddBtn;

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

@@ -25,7 +25,7 @@ var getSchemaDefaultValue = function getSchemaDefaultValue(schema) {
     }
   }
 };
-var getDefaultValue = function getDefaultValue(defaultValue, schema) {
+export var getDefaultValue = function getDefaultValue(defaultValue, schema) {
   if (isValid(defaultValue)) return clone(defaultValue);
   if (Array.isArray(schema === null || schema === void 0 ? void 0 : schema.items)) return getSchemaDefaultValue(schema === null || schema === void 0 ? void 0 : schema.items[0]);
   return getSchemaDefaultValue(schema === null || schema === void 0 ? void 0 : schema.items);

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

@@ -0,0 +1,18 @@
+/** height="auto" 时明细区最多显示的行数，超出后表格内部滚动 */
+export declare const ARRAY_TABLE_AUTO_MAX_ROWS = 10;
+export interface AutoHeightInput {
+    rowCount: number;
+    rowHeight: number;
+    headerHeight: number;
+    /** 合计行（固定在底部，占一行高度） */
+    hasSummary?: boolean;
+    /** 带行内错误文字、被撑高的行数 */
+    feedbackRows?: number;
+    minRows?: number;
+    maxRows?: number;
+}
+/**
+ * height="auto"：按行数算出网格高度，免得空表留大片空白、行少时不必手算像素。
+ * AG Grid 的 domLayout=autoHeight 会让合计行与滚动行为失效，这里改为按密度三档的行高直接计算。
+ */
+export declare const calcAutoGridHeight: ({ rowCount, rowHeight, headerHeight, hasSummary, feedbackRows, minRows, maxRows, }: AutoHeightInput) => number;

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

@@ -0,0 +1,25 @@
+import { ROW_FEEDBACK_EXTRA_HEIGHT } from "./rowFeedback";
+
+/** height="auto" 时明细区最多显示的行数，超出后表格内部滚动 */
+export var ARRAY_TABLE_AUTO_MAX_ROWS = 10;
+
+/** 表格外框上下各 1px 边线 */
+var BORDER = 2;
+/**
+ * height="auto"：按行数算出网格高度，免得空表留大片空白、行少时不必手算像素。
+ * AG Grid 的 domLayout=autoHeight 会让合计行与滚动行为失效，这里改为按密度三档的行高直接计算。
+ */
+export var calcAutoGridHeight = function calcAutoGridHeight(_ref) {
+  var rowCount = _ref.rowCount,
+    rowHeight = _ref.rowHeight,
+    headerHeight = _ref.headerHeight,
+    hasSummary = _ref.hasSummary,
+    _ref$feedbackRows = _ref.feedbackRows,
+    feedbackRows = _ref$feedbackRows === void 0 ? 0 : _ref$feedbackRows,
+    _ref$minRows = _ref.minRows,
+    minRows = _ref$minRows === void 0 ? 1 : _ref$minRows,
+    _ref$maxRows = _ref.maxRows,
+    maxRows = _ref$maxRows === void 0 ? ARRAY_TABLE_AUTO_MAX_ROWS : _ref$maxRows;
+  var rows = Math.min(Math.max(rowCount, minRows), Math.max(maxRows, minRows));
+  return headerHeight + rows * rowHeight + (hasSummary ? rowHeight : 0) + Math.min(feedbackRows, rows) * ROW_FEEDBACK_EXTRA_HEIGHT + BORDER;
+};

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

@@ -22,11 +22,11 @@ export declare function findRemovalAction(field: ArrayField, index: number, acti
 export declare function removeSelectedRows(field: ArrayField, ids: string[], actions: RemovalAction[], getId: (row: any) => string, onRemove?: (index: number) => void, event?: React.MouseEvent): boolean;
 /** 公共明细表格的勾选及批量删除，沿用业务行权限、行标识与删除通知。@author nokecy */
 export declare function useArrayTableBatchRemove(field: ArrayField, sources: ObservableColumnSource[], props: ArrayTableProps, apiRef: React.MutableRefObject<GridApi | undefined>, getId: (row: any) => string): {
-    rowSelection: "multiple" | "single" | import("ag-grid-community/dist/types/src/entities/gridOptions").SingleRowSelectionOptions<any, any> | import("ag-grid-community/dist/types/src/entities/gridOptions").MultiRowSelectionOptions<any, any> | {
+    rowSelection: "single" | "multiple" | import("ag-grid-community/dist/types/src/entities/gridOptions").SingleRowSelectionOptions<any, any> | import("ag-grid-community/dist/types/src/entities/gridOptions").MultiRowSelectionOptions<any, any> | {
         isRowSelectable: (node: IRowNode) => boolean;
         headerCheckbox?: boolean | undefined;
         selectAll?: "filtered" | undefined;
-        mode: "singleRow" | "multiRow";
+        mode: "multiRow" | "singleRow";
         checkboxes: boolean;
         enableClickSelection: boolean;
     } | undefined;

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

@@ -0,0 +1,18 @@
+import React from 'react';
+/** 格内控件的稳定标记值，键盘与浏览器测试按它定位，不依赖 antd 的内部类名。 */
+export type CellEditorKind = 'select' | 'date' | 'number' | 'text';
+/** 按 x-component 判定控件类别；开关、业务自定义组件等不在表内，不打标记（避免误导）。 */
+export declare const resolveCellEditorKind: (component: unknown) => CellEditorKind | undefined;
+/**
+ * 面板是否展开：下拉看 antd 的 open 类；日期面板挂在 body 下，只能「控件聚焦且存在可见面板」近似判断。
+ * 直接读 DOM 而不进 React 状态，避免每次开合让整格重渲。
+ */
+export declare const isCellEditorOpen: (root: Element, kind: CellEditorKind) => boolean;
+/**
+ * 给格内控件加 data-array-cell-editor / data-open 标记。display:contents 不产生盒子，不改变格内布局。
+ * 没有类别（不认识的组件）时原样返回子节点。@author nokecy
+ */
+export declare const CellEditorMarker: ({ kind, children }: {
+    kind?: CellEditorKind | undefined;
+    children: React.ReactNode;
+}) => React.JSX.Element;

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

@@ -0,0 +1,84 @@
+import React, { useEffect, useRef } from 'react';
+
+/** 格内控件的稳定标记值，键盘与浏览器测试按它定位，不依赖 antd 的内部类名。 */
+import { Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
+var KIND_BY_COMPONENT = {
+  Select: 'select',
+  TreeSelect: 'select',
+  Cascader: 'select',
+  DatePicker: 'date',
+  'DatePicker.RangePicker': 'date',
+  TimePicker: 'date',
+  'TimePicker.RangePicker': 'date',
+  InputNumber: 'number',
+  NumberPicker: 'number',
+  Input: 'text',
+  'Input.TextArea': 'text',
+  Password: 'text'
+};
+
+/** 按 x-component 判定控件类别；开关、业务自定义组件等不在表内，不打标记（避免误导）。 */
+export var resolveCellEditorKind = function resolveCellEditorKind(component) {
+  return typeof component === 'string' ? KIND_BY_COMPONENT[component] : undefined;
+};
+
+/**
+ * 面板是否展开：下拉看 antd 的 open 类；日期面板挂在 body 下，只能「控件聚焦且存在可见面板」近似判断。
+ * 直接读 DOM 而不进 React 状态，避免每次开合让整格重渲。
+ */
+export var isCellEditorOpen = function isCellEditorOpen(root, kind) {
+  if (kind === 'select') return !!root.querySelector('.ant-select-open');
+  if (kind === 'date') {
+    return !!root.querySelector('.ant-picker-focused') && !!document.querySelector('.ant-picker-dropdown:not(.ant-picker-dropdown-hidden)');
+  }
+  return false;
+};
+
+/**
+ * 给格内控件加 data-array-cell-editor / data-open 标记。display:contents 不产生盒子，不改变格内布局。
+ * 没有类别（不认识的组件）时原样返回子节点。@author nokecy
+ */
+export var CellEditorMarker = function CellEditorMarker(_ref) {
+  var kind = _ref.kind,
+    children = _ref.children;
+  var ref = useRef(null);
+  useEffect(function () {
+    var root = ref.current;
+    if (!root || !kind || kind !== 'select' && kind !== 'date') return;
+    var sync = function sync() {
+      if (isCellEditorOpen(root, kind)) root.setAttribute('data-open', '1');else root.removeAttribute('data-open');
+    };
+    // 弹层开合发生在 antd 内部，类名变化与聚焦/点击/按键之后下一拍再读一次。
+    var later = function later() {
+      window.setTimeout(sync, 0);
+    };
+    var observer = new MutationObserver(sync);
+    observer.observe(root, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['class']
+    });
+    var events = ['focusin', 'focusout', 'click', 'keyup'];
+    events.forEach(function (name) {
+      return root.addEventListener(name, later);
+    });
+    return function () {
+      observer.disconnect();
+      events.forEach(function (name) {
+        return root.removeEventListener(name, later);
+      });
+    };
+  }, [kind]);
+  if (!kind) return /*#__PURE__*/_jsx(_Fragment, {
+    children: children
+  });
+  return /*#__PURE__*/_jsx("div", {
+    ref: ref,
+    "data-array-cell-editor": kind,
+    style: {
+      display: 'contents'
+    },
+    children: children
+  });
+};

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

@@ -0,0 +1,29 @@
+import type { GridApi } from 'ag-grid-community';
+import type { ErrorLocator } from '@nokecy/formily-antd';
+/** ArrayTable 的一列：AG-Grid 列 id 与它承载的内层数据字段名（Column key 与字段名可能不同，如设计器形态）。 */
+export type ErrorLocatorColumn = {
+    colId: string;
+    dataName?: string;
+    title?: string;
+};
+type Deps = {
+    field: any;
+    getContainer: () => HTMLElement | null | undefined;
+    getApi: () => GridApi | undefined;
+    getColumns: () => ErrorLocatorColumn[];
+    /** 行数据 -> AG-Grid 行 id（与 getRowId 同一套） */
+    getRowId: (row: any) => string;
+    focus: (params: {
+        rowIndex: number;
+        colId: string;
+    }) => Promise<HTMLElement | undefined>;
+};
+/**
+ * 提交校验失败时 ArrayTable 的错误定位器（注册到 adapters 的 form-error-focus，见 registerErrorLocator）。
+ *
+ * 错误格可能不在 DOM 里（行被虚拟化、懒挂载格卸回了文本），按 DOM 找不到，所以按 Formily 的错误列表定位：
+ * 取表内最靠前的（先行后列，行按当前显示顺序、列按当前列序），ensureIndexVisible / ensureColumnVisible 滚到位，
+ * 再激活该格并聚焦输入。@author nokecy
+ */
+export declare const createArrayTableErrorLocator: (deps: Deps) => ErrorLocator;
+export {};

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/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 {};