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

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

@@ -0,0 +1,152 @@
+"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.CellFocusScope = void 0;
+var _react = _interopRequireWildcard(require("react"));
+var _cellInteractionLock = require("./cellInteractionLock");
+var _jsxRuntime = require("react/jsx-runtime");
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != _typeof(e) && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && Object.prototype.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+/**
+ * 判断「焦点离开了这个单元格」的作用域,给懒挂载格「用完卸回纯文本」用。
+ *
+ * 用 React 合成的 onFocus/onBlur 判断焦点变化:合成事件会沿 React 树冒泡,穿过 portal。
+ * 下拉面板、日期面板、选择对话框这类渲染到 body 上的弹层,焦点进去时对本格仍是「格内」。
+ * 同时监听指针离开:点击到不可聚焦的文本格或页面空白不会触发 blur,需要按点击位置恢复展示态；
+ * portal 内的指针事件仍沿 React 树到达本作用域,不会被当作离开。
+ *
+ * 离开不立刻判定,而是推到下一个任务再看:焦点从输入框换到格内别的元素(或弹层)时,
+ * blur 之后紧跟着 focus,后者会作废这次判定。单纯 blur 时若 activeElement 仍在格内
+ * (如窗口切走),不算离开；指针明确点击到作用域外则按离开处理。
+ *
+ * 用 display: contents,不产生盒子,不改变单元格里原有的布局。
+ *
+ * @author nokecy
+ */
+
+var CellFocusScope = exports.CellFocusScope = function CellFocusScope(_ref) {
+  var onLeave = _ref.onLeave,
+    children = _ref.children;
+  var rootRef = (0, _react.useRef)(null);
+  var timerRef = (0, _react.useRef)(undefined);
+  var dateTimerRef = (0, _react.useRef)(undefined);
+  var acquireParentInteractionLock = (0, _react.useContext)(_cellInteractionLock.CellInteractionLockContext);
+  // 通过 React portal 渲染到 body 的弹层仍属于当前格；记录经过本作用域的指针事件，
+  // 避免日期/下拉弹层中的点击被 document 级离开检测误判。@author nokecy
+  var pointerEventsInScopeRef = (0, _react.useRef)(new WeakSet());
+  var focusWithinRef = (0, _react.useRef)(false);
+  var interactionLocksRef = (0, _react.useRef)(new Set());
+  // 每次焦点回到格内、或卸载时递增;进行中的异步判定拿它判断自己是否已过期
+  var generationRef = (0, _react.useRef)(0);
+  var onLeaveRef = (0, _react.useRef)(onLeave);
+  onLeaveRef.current = onLeave;
+  var cancel = (0, _react.useCallback)(function () {
+    generationRef.current += 1;
+    window.clearTimeout(timerRef.current);
+    window.clearTimeout(dateTimerRef.current);
+  }, []);
+  var scheduleLeave = (0, _react.useCallback)(function () {
+    var pointerLeftScope = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : false;
+    var hadFocus = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : focusWithinRef.current;
+    var pointerEvent = arguments.length > 2 ? arguments[2] : undefined;
+    cancel();
+    var generation = generationRef.current;
+    timerRef.current = window.setTimeout(function () {
+      var _rootRef$current;
+      // 对话框仍打开时，按钮 loading、候选清空等引起的暂时失焦不结束整次选择交互。
+      // 结束条件由弹层自身关闭控制，避免连同弹窗一起卸成静默文本。@author nokecy
+      if (interactionLocksRef.current.size > 0) return;
+      // document 捕获先于 React portal 的捕获处理；到任务末再按完整的 React 作用域判定。
+      // 选择器弹层内的点击不结束当前格的编辑。@author nokecy
+      if (pointerEvent && pointerEventsInScopeRef.current.has(pointerEvent)) return;
+      // blur 后 activeElement 仍在本格通常是窗口切走或格内弹层切焦点，不算离开。
+      // 指针明确点到本格/其弹层之外时，即使目标不可聚焦导致 activeElement 没变，也应离开。
+      if (!pointerLeftScope && (_rootRef$current = rootRef.current) !== null && _rootRef$current !== void 0 && _rootRef$current.contains(document.activeElement)) return;
+      onLeaveRef.current(function () {
+        return generation !== generationRef.current;
+      }, hadFocus);
+    }, 0);
+  }, [cancel]);
+  var acquireInteractionLock = (0, _react.useCallback)(function () {
+    var lock = Symbol('cell-popup');
+    interactionLocksRef.current.add(lock);
+    cancel();
+    // Editable 与懒挂载格可以嵌套；弹层同时占用所有父格，防止外层先卸掉选择器。@author nokecy
+    var releaseParent = acquireParentInteractionLock === null || acquireParentInteractionLock === void 0 ? void 0 : acquireParentInteractionLock();
+    return function () {
+      if (!interactionLocksRef.current.delete(lock)) return;
+      releaseParent === null || releaseParent === void 0 || releaseParent();
+      // 弹层关闭后恢复通常的校验与静默流程；不是永久屏蔽失焦。
+      // 卸载时 ref 已移除，不为已经销毁的单元格再排任务。@author nokecy
+      if (interactionLocksRef.current.size === 0 && rootRef.current) scheduleLeave(true, true);
+    };
+  }, [cancel, scheduleLeave, acquireParentInteractionLock]);
+  var handleFocus = function handleFocus() {
+    focusWithinRef.current = true;
+    cancel();
+  };
+  var handleBlur = function handleBlur() {
+    var hadFocus = focusWithinRef.current;
+    focusWithinRef.current = false;
+    scheduleLeave(false, hadFocus);
+  };
+  var handlePointerDownCapture = function handlePointerDownCapture(event) {
+    pointerEventsInScopeRef.current.add(event.nativeEvent);
+    // 再次点击原输入框不一定产生 focus，仍须作废此前离开时发起的异步校验。@author nokecy
+    cancel();
+  };
+  var handleClickCapture = function handleClickCapture(event) {
+    var target = event.target;
+    if (!(target instanceof Element)) return;
+    // DatePicker 选中日期后会关闭弹层，但通常把焦点留在输入框里，单靠 blur 无法恢复静默态。
+    // 只处理日期面板里的提交动作；范围日期选择第一端后面板仍开着，不会提前退出编辑。
+    // @author nokecy
+    var selected = target.closest('.ant-picker-dropdown .ant-picker-cell-inner, .ant-picker-dropdown .ant-picker-ok, .ant-picker-dropdown .ant-picker-today-btn, .ant-picker-dropdown .ant-picker-now-btn');
+    if (!selected) return;
+    var dropdown = selected.closest('.ant-picker-dropdown');
+    window.clearTimeout(dateTimerRef.current);
+    var generation = generationRef.current;
+    dateTimerRef.current = window.setTimeout(function () {
+      if (generation !== generationRef.current || !rootRef.current) return;
+      if (dropdown !== null && dropdown !== void 0 && dropdown.isConnected && !dropdown.classList.contains('ant-picker-dropdown-hidden')) return;
+      scheduleLeave(true, true);
+    }, 0);
+  };
+  (0, _react.useEffect)(function () {
+    var handleDocumentPointerDown = function handleDocumentPointerDown(event) {
+      var root = rootRef.current;
+      if (!root) return;
+      var target = event.target;
+      // DOM 内点击以及 React portal 子树内点击都属于当前格的交互。
+      if (target instanceof Node && root.contains(target) || pointerEventsInScopeRef.current.has(event)) return;
+      // 新增行的必填空格也会预先挂载控件，但可能从未获得焦点；同样需要响应离开，
+      // 由 onLeave 根据 hadFocus 决定是否校验未触碰的空必填格。@author nokecy
+      scheduleLeave(true, focusWithinRef.current, event);
+    };
+
+    // 捕获阶段也能收到被表单控件阻止冒泡的点击，避免必须点工具栏才退出编辑。
+    // portal 的归属在延迟任务中确认。@author nokecy
+    document.addEventListener('pointerdown', handleDocumentPointerDown, true);
+    return function () {
+      document.removeEventListener('pointerdown', handleDocumentPointerDown, true);
+      cancel();
+    };
+  }, [cancel, scheduleLeave]);
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_cellInteractionLock.CellInteractionLockContext.Provider, {
+    value: acquireInteractionLock,
+    children: /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+      ref: rootRef,
+      style: {
+        display: 'contents'
+      },
+      onFocusCapture: handleFocus,
+      onBlurCapture: handleBlur,
+      onClickCapture: handleClickCapture,
+      onPointerDownCapture: handlePointerDownCapture,
+      children: children
+    })
+  });
+};

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

@@ -0,0 +1,13 @@
+/// <reference types="react" />
+/**
+ * 单元格弹层的交互占用。最后一个弹层关闭前，暂时失焦不能卸载单元格。
+ * 不在懒单元格中使用时无需任何额外处理。
+ * @author nokecy
+ */
+export declare const CellInteractionLockContext: import("react").Context<(() => () => void) | undefined>;
+/**
+ * 将弹层的打开状态绑定到所属单元格，支持嵌套弹层并在关闭或卸载时释放。
+ * 使用布局阶段同步占用，避免打开弹层的同一次交互产生的失焦任务先卸载控件。
+ * @author nokecy
+ */
+export declare const useCellInteractionLock: (open: boolean) => void;

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

@@ -0,0 +1,26 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useCellInteractionLock = exports.CellInteractionLockContext = void 0;
+var _react = require("react");
+/**
+ * 单元格弹层的交互占用。最后一个弹层关闭前，暂时失焦不能卸载单元格。
+ * 不在懒单元格中使用时无需任何额外处理。
+ * @author nokecy
+ */
+var CellInteractionLockContext = exports.CellInteractionLockContext = /*#__PURE__*/(0, _react.createContext)(undefined);
+
+/**
+ * 将弹层的打开状态绑定到所属单元格，支持嵌套弹层并在关闭或卸载时释放。
+ * 使用布局阶段同步占用，避免打开弹层的同一次交互产生的失焦任务先卸载控件。
+ * @author nokecy
+ */
+var useCellInteractionLock = exports.useCellInteractionLock = function useCellInteractionLock(open) {
+  var acquire = (0, _react.useContext)(CellInteractionLockContext);
+  (0, _react.useLayoutEffect)(function () {
+    if (open) return acquire === null || acquire === void 0 ? void 0 : acquire();
+    return undefined;
+  }, [acquire, open]);
+};

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

@@ -0,0 +1,8 @@
+import type { ColDef } from 'ag-grid-community';
+/** 明细列对齐：沿用 antd Table 的 `align` 写法。@author nokecy */
+export type ColumnAlign = 'left' | 'center' | 'right';
+/**
+ * 按列上的 `align` 补单元格与列头的对齐类名；没写或写错时原样返回。
+ * 对齐样式见 theme.ts（单元格里正在编辑的输入框同样跟随列对齐）。
+ */
+export declare function withColumnAlign(column: ColDef, align: unknown): ColDef;

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

@@ -0,0 +1,41 @@
+"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.withColumnAlign = withColumnAlign;
+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 _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread(); }
+function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+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 _iterableToArray(iter) { if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter); }
+function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) return _arrayLikeToArray(arr); }
+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; }
+/** 明细列对齐：沿用 antd Table 的 `align` 写法。@author nokecy */
+
+var appendClass = function appendClass(original, extra) {
+  var merge = function merge(classes) {
+    return Array.from(new Set([].concat(_toConsumableArray(Array.isArray(classes) ? classes : classes ? [classes] : []), [extra])));
+  };
+  return typeof original === 'function' ? function (params) {
+    return merge(original(params));
+  } : merge(original);
+};
+
+/**
+ * 按列上的 `align` 补单元格与列头的对齐类名；没写或写错时原样返回。
+ * 对齐样式见 theme.ts（单元格里正在编辑的输入框同样跟随列对齐）。
+ */
+function withColumnAlign(column, align) {
+  if (align !== 'left' && align !== 'center' && align !== 'right') return column;
+  return _objectSpread(_objectSpread({}, column), {}, {
+    cellClass: appendClass(column.cellClass, "qc-array-table-align-".concat(align))
+  }, align === 'right' ? {
+    headerClass: appendClass(column.headerClass, 'ag-right-aligned-header')
+  } : {});
+}

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

@@ -0,0 +1,39 @@
+/**
+ * ArrayTable 分组表头(多级表头)。
+ *
+ * 背景:schema 里的每个 ArrayTable.Column 被抽成「扁平」列定义(buildArrayTableColumns),
+ * 内部一批逻辑(懒挂载列识别、列方案还原、首列拖拽等)都按扁平列取值,不能改。
+ * 所以分组只在「交给 AG-Grid 的那一份 columnDefs」上做:
+ *  1. buildArrayTableColumns 生成列定义时,用 markHeaderGroup 把列声明的 headerGroup 记下来;
+ *  2. index.tsx 把扁平列定义交给 groupColumnDefs,得到含列组的 columnDefs 传给 AgGridReact。
+ *
+ * 分组名记在模块内的 WeakMap 里,不往 colDef 上塞自定义字段——AG-Grid 会把未知属性当作错误告警。
+ *
+ * 只支持一级分组;分组名相同但不相邻的列各自成组。
+ *
+ * @author nokecy
+ */
+import type { ColDef, ColGroupDef } from 'ag-grid-community';
+/**
+ * 记下列定义所属的表头分组。
+ * headerGroup 不是非空字符串(没声明、空串、纯空白)时不做任何事,该列按无分组处理。
+ * 返回传入的 colDef 本身,方便链式使用。
+ */
+export declare const markHeaderGroup: <T extends object>(colDef: T, headerGroup: unknown) => T;
+/**
+ * 把扁平列定义按「相邻且 headerGroup 相同」合并成 AG-Grid 列组。
+ *
+ *  - 相邻同名的列 -> 一个 { headerName, groupId, children } 列组;
+ *  - 同名但被别的列隔开 -> 各自成组,groupId 各不相同;
+ *  - 没声明分组的列原样保留(同一个对象);
+ *  - 一个分组也没有时直接返回传入的数组本身,没用到分组的表格行为零变化。
+ *
+ * groupId 由分组名派生(同名第 N 次出现追加 _N),同样的输入永远得到同样的 id:
+ * columnDefs 因别的原因重建时,AG-Grid 靠 groupId 认出还是那个列组,列组状态不丢。
+ *
+ * 有意不设 marryChildren:设了以后,任何打破组内相邻的列顺序(用户旧的扁平列方案、
+ * 列设置面板里跨组拖动的实时预览)都会被 AG-Grid 整体丢弃并报 error #39;不设则顺序照常生效,
+ * 组被隔开时表头显示成多段。
+ * openByDefault:列组默认展开(只对配了 columnGroupShow 的可折叠列组有意义)。
+ */
+export declare const groupColumnDefs: (colDefs: ColDef[]) => (ColDef | ColGroupDef)[];

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

@@ -0,0 +1,106 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.markHeaderGroup = exports.groupColumnDefs = void 0;
+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 分组表头(多级表头)。
+ *
+ * 背景:schema 里的每个 ArrayTable.Column 被抽成「扁平」列定义(buildArrayTableColumns),
+ * 内部一批逻辑(懒挂载列识别、列方案还原、首列拖拽等)都按扁平列取值,不能改。
+ * 所以分组只在「交给 AG-Grid 的那一份 columnDefs」上做:
+ *  1. buildArrayTableColumns 生成列定义时,用 markHeaderGroup 把列声明的 headerGroup 记下来;
+ *  2. index.tsx 把扁平列定义交给 groupColumnDefs,得到含列组的 columnDefs 传给 AgGridReact。
+ *
+ * 分组名记在模块内的 WeakMap 里,不往 colDef 上塞自定义字段——AG-Grid 会把未知属性当作错误告警。
+ *
+ * 只支持一级分组;分组名相同但不相邻的列各自成组。
+ *
+ * @author nokecy
+ */
+
+/** 列定义 -> 它在 schema 里声明的 headerGroup */
+var headerGroupOf = new WeakMap();
+
+/** 列组 id 前缀,与列方案里生成的 col_N 区分开 */
+var GROUP_ID_PREFIX = 'arrayTableGroup_';
+
+/**
+ * 记下列定义所属的表头分组。
+ * headerGroup 不是非空字符串(没声明、空串、纯空白)时不做任何事,该列按无分组处理。
+ * 返回传入的 colDef 本身,方便链式使用。
+ */
+var markHeaderGroup = exports.markHeaderGroup = function markHeaderGroup(colDef, headerGroup) {
+  if (typeof headerGroup === 'string' && headerGroup.trim() !== '') {
+    headerGroupOf.set(colDef, headerGroup);
+  }
+  return colDef;
+};
+
+/**
+ * 把扁平列定义按「相邻且 headerGroup 相同」合并成 AG-Grid 列组。
+ *
+ *  - 相邻同名的列 -> 一个 { headerName, groupId, children } 列组;
+ *  - 同名但被别的列隔开 -> 各自成组,groupId 各不相同;
+ *  - 没声明分组的列原样保留(同一个对象);
+ *  - 一个分组也没有时直接返回传入的数组本身,没用到分组的表格行为零变化。
+ *
+ * groupId 由分组名派生(同名第 N 次出现追加 _N),同样的输入永远得到同样的 id:
+ * columnDefs 因别的原因重建时,AG-Grid 靠 groupId 认出还是那个列组,列组状态不丢。
+ *
+ * 有意不设 marryChildren:设了以后,任何打破组内相邻的列顺序(用户旧的扁平列方案、
+ * 列设置面板里跨组拖动的实时预览)都会被 AG-Grid 整体丢弃并报 error #39;不设则顺序照常生效,
+ * 组被隔开时表头显示成多段。
+ * openByDefault:列组默认展开(只对配了 columnGroupShow 的可折叠列组有意义)。
+ */
+var groupColumnDefs = exports.groupColumnDefs = function groupColumnDefs(colDefs) {
+  if (!colDefs.some(function (colDef) {
+    return headerGroupOf.has(colDef);
+  })) return colDefs;
+  var usedGroupIds = new Set();
+  var makeGroupId = function makeGroupId(name) {
+    var id = "".concat(GROUP_ID_PREFIX).concat(name);
+    for (var n = 2; usedGroupIds.has(id); n++) {
+      id = "".concat(GROUP_ID_PREFIX).concat(name, "_").concat(n);
+    }
+    usedGroupIds.add(id);
+    return id;
+  };
+  var result = [];
+  var current = null;
+  var _iterator = _createForOfIteratorHelper(colDefs),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var colDef = _step.value;
+      var name = headerGroupOf.get(colDef);
+      if (name === undefined) {
+        current = null;
+        result.push(colDef);
+      } else if (current && current.name === name) {
+        current.group.children.push(colDef);
+      } else {
+        var group = {
+          headerName: name,
+          groupId: makeGroupId(name),
+          openByDefault: true,
+          children: [colDef]
+        };
+        current = {
+          name: name,
+          group: group
+        };
+        result.push(group);
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return result;
+};

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

@@ -0,0 +1,126 @@
+import { ColDef } from 'ag-grid-community';
+/**
+ * 列配置类型定义
+ */
+export interface ColumnConfig {
+    /** 列标题 */
+    headerName: string;
+    /** 数据字段 */
+    dataIndex: string;
+    /** 列宽度 */
+    width?: number;
+    /** 最小宽度 */
+    minWidth?: number;
+    /** 最大宽度 */
+    maxWidth?: number;
+    /** 是否可调整大小 */
+    resizable?: boolean;
+    /** 是否可排序 */
+    sortable?: boolean;
+    /** 是否可筛选 */
+    filter?: boolean | string;
+    /** 对齐方式 */
+    align?: 'left' | 'center' | 'right';
+    /** 是否固定列 */
+    pinned?: 'left' | 'right' | null;
+    /** 是否隐藏 */
+    hide?: boolean;
+    /** 是否省略显示 */
+    ellipsis?: boolean;
+    /** 是否可编辑 */
+    editable?: boolean;
+    /** 自定义 AG-Grid 配置 */
+    agGridProps?: Partial<ColDef>;
+}
+/**
+ * 文本列配置
+ * 用于显示和编辑文本内容
+ */
+export declare const createTextColumn: (config: ColumnConfig) => ColumnConfig;
+/**
+ * 数字列配置
+ * 用于显示和编辑数字内容
+ */
+export declare const createNumberColumn: (config: ColumnConfig) => ColumnConfig;
+/**
+ * 日期列配置
+ * 用于显示和编辑日期内容
+ */
+export declare const createDateColumn: (config: ColumnConfig) => ColumnConfig;
+/**
+ * 选择列配置
+ * 用于下拉选择类型的列
+ */
+export declare const createSelectColumn: (config: ColumnConfig) => ColumnConfig;
+/**
+ * 操作列配置
+ * 用于行操作按钮列
+ */
+export declare const createOperationColumn: (config: Omit<ColumnConfig, 'dataIndex'>) => ColumnConfig;
+/**
+ * 序号列配置
+ * 用于显示行序号
+ */
+export declare const createIndexColumn: (config?: Partial<ColumnConfig>) => ColumnConfig;
+/**
+ * 只读列配置
+ * 用于显示不可编辑的内容
+ */
+export declare const createReadOnlyColumn: (config: ColumnConfig) => ColumnConfig;
+/**
+ * 固定左侧列配置
+ */
+export declare const createPinnedLeftColumn: (config: ColumnConfig) => ColumnConfig;
+/**
+ * 固定右侧列配置
+ */
+export declare const createPinnedRightColumn: (config: ColumnConfig) => ColumnConfig;
+/**
+ * 百分比列配置
+ * 用于显示百分比数值
+ */
+export declare const createPercentColumn: (config: ColumnConfig) => ColumnConfig;
+/**
+ * 货币列配置
+ * 用于显示货币金额
+ */
+export declare const createCurrencyColumn: (config: ColumnConfig) => ColumnConfig;
+/**
+ * 批量创建列配置
+ * @param columns 列配置数组
+ * @returns 标准化的列配置数组
+ */
+export declare const createColumns: (columns: ColumnConfig[]) => ColumnConfig[];
+/**
+ * 列配置预设
+ */
+export declare const ColumnPresets: {
+    /** 文本列 */
+    text: (config: ColumnConfig) => ColumnConfig;
+    /** 数字列 */
+    number: (config: ColumnConfig) => ColumnConfig;
+    /** 日期列 */
+    date: (config: ColumnConfig) => ColumnConfig;
+    /** 选择列 */
+    select: (config: ColumnConfig) => ColumnConfig;
+    /** 操作列 */
+    operation: (config: Omit<ColumnConfig, 'dataIndex'>) => ColumnConfig;
+    /** 序号列 */
+    index: (config?: Partial<ColumnConfig>) => ColumnConfig;
+    /** 只读列 */
+    readOnly: (config: ColumnConfig) => ColumnConfig;
+    /** 固定左侧列 */
+    pinnedLeft: (config: ColumnConfig) => ColumnConfig;
+    /** 固定右侧列 */
+    pinnedRightColumn: (config: ColumnConfig) => ColumnConfig;
+    /** 百分比列 */
+    percent: (config: ColumnConfig) => ColumnConfig;
+    /** 货币列 */
+    currency: (config: ColumnConfig) => ColumnConfig;
+};
+/**
+ * 转换为 AG-Grid 列定义
+ * @param config 列配置
+ * @returns AG-Grid ColDef
+ */
+export declare const toAgGridColDef: (config: ColumnConfig) => Partial<ColDef>;