@canvas-components/pivot-table 0.1.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 canvas-components contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @canvas-components/pivot-table
+
+独立于 `list-table` 的纯原生数据透视表内核。包内不依赖 React，React 接入由 `@canvas-components/react-pivot-table` 提供。
+
+## 能力
+
+- 双轴多级维度树与稳定节点 ID
+- `sum`、`avg`、`count`、`distinctCount`、`min`、`max` 和自定义聚合器
+- 稀疏聚合、小计、总计和多指标行列布局
+- 四区 Canvas、虚拟滚动、展开收起、拖拽矩形选区和下钻
+- 支持单元格、矩形选区与指标整列复制
+- 维度成员排序、聚合前过滤和共享表头过滤面板
+- CSV/XLSX 导出与版本化状态快照
+
+## React 示例
+
+```tsx
+import { ReactPivotTable } from "@canvas-components/react-pivot-table";
+
+<ReactPivotTable
+  dataSource={records}
+  rows={[{ dataIndex: "region", allowFilter: true }]}
+  columns={[{ key: "year", dataIndex: "year" }]}
+  indicators={[{ key: "sales", dataIndex: "sales", aggregator: "sum" }]}
+/>;
+```
+
+`rows` 与 `columns` 的字段命名、`render` 回调及排序过滤配置与
+`ListTableColumn` 保持一致，可以从 ListTable 列配置中直接选取维度列。
+PivotTable 会在未提供 `key` 时使用 `dataIndex` 生成稳定维度标识；
+`defaultExpandDepth` 是透视维度额外支持的展开配置。
+
+过滤发生在聚合前。`filters`、`sorts`、`selection` 和 `expandedRowKeys`/`expandedColumnKeys` 可受控；不传时由实例维护。
+
+## 原生实例 API
+
+```ts
+import { PivotTable } from "@canvas-components/pivot-table";
+
+const table = new PivotTable(container, options);
+table.mount();
+
+table.getPivotModel();
+table.getVisibleRowNodes();
+table.getVisibleColumnNodes();
+table.selectCell(address);
+table.selectNode("row", nodeId);
+table.scrollToCell(address);
+table.setDimensionFilter("row", "region", filter);
+table.setDimensionSort("row", "region", "asc");
+table.setIndicatorSort({
+  axis: "row",
+  dimensionKey: "region",
+  indicatorKey: "sales",
+  direction: "desc",
+});
+table.getCellRecords(cellContext);
+table.exportCsv({ mode: "visible" });
+table.exportXlsx({ mode: "all", sheetName: "销售透视" });
+table.getState();
+table.restoreState(snapshot);
+table.getDebugSnapshot();
+
+table.destroy();
+```
+
+`ReactPivotTable` 的 ref 透传选择、筛选、排序、导出、状态快照和调试方法，不在 React 层复制聚合或布局逻辑。
+
+## 自定义聚合器
+
+```ts
+const weightedAverage = {
+  create: () => ({ weightedValue: 0, weight: 0 }),
+  add: (state, value, context) => {
+    const weight = Number(context.record.weight ?? 0);
+    state.weightedValue += Number(value ?? 0) * weight;
+    state.weight += weight;
+  },
+  finalize: (state) =>
+    state.weight === 0 ? null : state.weightedValue / state.weight,
+};
+
+const indicators = [
+  {
+    key: "weightedPrice",
+    dataIndex: "price",
+    aggregator: weightedAverage,
+  },
+];
+```
+
+聚合器状态按维度组合隔离。`add` 不得复用其他单元格状态；需要大数据分块时可实现 `merge`。