@done-coding/admin-core 0.22.2 → 0.22.3-alpha.0

package/src/components/data-view/docs/README-DataGridView.md

@@ -0,0 +1,139 @@
+# DataGridView（网格数据容器）
+
+> 对齐 TableMain 主 props 的**网格数据容器**：自持**存量累加**状态机（api + query + fetchNextPage + hasMore），内部复用 InfiniteListView（按 `gridColumns` chunk 行虚拟化）+ TableToolbar（存量上下文）+ 列配置驱动卡片渲染。
+> 走「数据存量 + 虚拟列表」路径，**非分页**——无分页器，到底提示"我是有底线的"。
+> 范式页：`apps/reference/src/pages/data-view/grid/`
+> 类型：data-view 族公共组件（进 core 顶层 export）；**推荐经 `ListLayout` 门面使用**（`viewMode="grid"`），独立使用需自配上下文（与 TableMain 独立使用成本相同）
+
+## 定位
+
+- **何时用**：数据量大、需要滚动到底加载更多 + 卡片网格形态的列表页；经 `ListLayout` `viewMode="grid"` 接入
+- **何时不用**：标准表格/分页用 `TableMain`（`viewMode="table"`）；仅当前页卡片渲染用 `TableMain` + `customView`（`DataListView`）
+- **数据路径与 TableMain 不同构**：TableMain = 分页替换当前页；DataGridView = **存量累加**（滚动到底 append 下一页，直到 hasMore=false）。两者是两套数据状态机，故**不共存于同一组件内**——切换在 `ListLayout` 的 `viewMode` 层
+- 泛型三参：`T` 行 / `SQ` 静态查询参数 / `F` 注入对象类型；`query` 变化时清空存量从第 1 页重新累加
+- 内部结构：数据容器（本组件）→ InfiniteListView（IO 哨兵触发 + 虚拟化 + 底部三态）→ gridColumns 卡片网格
+
+## 快速上手（最小可用）
+
+经 `ListLayout` 门面（`apps/reference/src/pages/data-view/grid/`）：
+
+```vue
+<ListLayout
+  v-model:view-mode="viewMode"
+  :list="searchItems"
+  :api="api"
+  :columns="columns"
+  row-key="id"
+  :grid-columns="4"
+>
+  <template #custom-view-item="{ row, index }">
+    <div class="card">{{ index + 1 }}. {{ row.name }}</div>
+  </template>
+</ListLayout>
+```
+
+直接使用（对齐 TableMain 三必传）：
+
+```vue
+<DataGridView
+  ref="gridRef"
+  :api="api"
+  :columns="columns"
+  row-key="id"
+  :page-size-init="20"
+  :grid-columns="4"
+>
+  <template #custom-view-item="{ row, index }"> ... </template>
+</DataGridView>
+```
+
+**要点**：
+
+- 三必传 `api` / `columns` / `rowKey`；`api` 收到 `query` 深合并 `page.page/page.pageSize`（键名 `APP_API_LIST_MODEL_KEY_CONFIG` 单源），返回 `TableApiResult<T>` 的 `items` + `page.totalRecord`；`hasMore` 由 `total` 与已累加量比较
+- **每批** `pageSizeInit`（默认 20）条，滚动到底自动 append 下一页；`finished`（hasMore=false）底部显示"我是有底线的"
+- 出错 → 底部错误原因 + 「点击重试」手动重发
+- `#custom-view-item` 缺省时基于 `columns` 渲染朴素卡片（每列一行 `label: value`，render 走 `render`、非 render 走 `row[prop]`）——**只传 columns 即开箱出卡片**，插槽可覆盖
+- keepAlive 返回刷新由 core 内置承担（onActivated 清空重拉）——[MUST NOT] app 侧再手写刷新信号
+
+## 能力边界 / 按需使用
+
+- **默认即够用：存量累加 + 滚动加载 + 错误重试 + 到底提示 + 虚拟化 + 工具栏 + refine 布局全开**——只传 `api`/`columns`/`rowKey` 即得标准网格页。
+- **高度链三选一（同 TableMain 判据）**：`refine` 默认开；`maxHeight` 显式定高仅嵌定高容器时；`viewportHeight` 仅嵌套弹层消费外层 scope 时。
+- **`maxHeight` 默认 `"100vh"`（满视口高）**：非 refine 且外部未显式传时兜底限高，容器内部滚动、杜绝无限顶开；数字 = px，字符串 = CSS 长度（"50vh" 等），外部认为有更合适的值直接显式传入覆盖。
+- `fillHeight`：默认关；数据稀疏/为空时撑满、底部状态贴底时开。
+- `gridColumns`：**定列数**等宽网格（默认 4），卡片自动填满格子（`repeat(gridColumns, 1fr)`）；消费方在 `#custom-view-item` 里只管卡片**内容**，宽度不用设。传**对象**则走 el-col span 制断点配置（24 栅格，对齐 FormSearch layout 心智）：`{ xs: 24, sm: 12, md: 8, lg: 6, xl: 4 }` = 1/2/3/4/6 列（列数 = 24 / span），未配断点回落 ≤ 当前断点最近一档。
+- `pageSizeInit`：每批加载条数（对齐 TableMain 的 pageSizeInit"初始一次设置"机制，默认 20）；**批次固定，运行期不改**。
+- `infiniteListProps`：InfiniteListView 配置透传（`distance` / `endText` / `errorText` / `pullRefresh` / `estimateSize` / `overscan` 等）。
+- `skeleton`：默认开（冷启网格卡片骨架）。
+- **空态双态**：非加载态空数据按 `api` 是否至少被调用过一次区分——从未调用（`initialSearch=false` 首屏）→「欢迎触发查询」；已调用无数据 → ElEmpty「暂无数据」。
+- **激活刷新条件化**：`onActivated` 自动刷新仅「已发生过查询」后生效（`hasRequested` 自判），与 TableMain 同语义。
+- **完整能力演示**：`apps/reference/src/pages/data-view/grid/`。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（泛型 `T` 行 / `SQ` 静态 / `F` 注入）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `api` | `(params: TableApiParams<SQ>) => Promise<TableApiResult<T>>`（必传） | — | 列表请求；params = query 深合并 page.page/page.pageSize（键名 APP_API_LIST_MODEL_KEY_CONFIG 定） |
+| `columns` | `ElTableColumnProps<T,F>[]`（必传） | — | 列配置数组（驱动默认卡片渲染） |
+| `rowKey` | `Extract<keyof T,string> \| ((row:T)=>string)`（必传） | — | 行/卡唯一键 |
+| `query` | `SQ` | — | 静态查询参数；变化时清空存量从第 1 页重新累加 |
+| `pageSizeInit` | `number` | `20` | 每批加载条数（批次固定，运行期不改） |
+| `gridColumns` | `number \| Partial<Record<Breakpoint, number>>` | `4` | 定列数（`repeat(N, 1fr)`）；对象 = el-col span 制断点配置（24 栅格，列数 = 24 / span，未配档回落更小档） |
+| `maxHeight` | `number \| string` | `"100vh"` | 数据区最大高度；数字 px / 字符串 CSS 长度；默认满视口高（非 refine 兜底限高） |
+| `refine` | `boolean` | `true` | 精细化布局：无 maxHeight 时按 viewport 高减工具栏/底部得出数据区高 |
+| `refineReduceHeight` | `number` | `0` | refine 模式预留高度减量 |
+| `viewportHeight` | `number` | — | 显式指定视口可用高（优先级最高）；缺省走 SCOPE_VIEWPORT_MAX_HEIGHT scope 链 + fallback 0（500 floor 兜底） |
+| `parentChannel` | `string` | — | 定向消费的祖先 scope 标识；setup 期快照 |
+| `fillHeight` | `boolean` | `false` | 数据滚动区 min-height 撑满可用高、底部状态贴底 |
+| `dataViewMaxHeightMinValue` | `number` | `500` | 数据视口最大高最小值 floor 兜底 |
+| `injectInfo` | `F` | — | 注入列作用域/卡片作用域的额外对象 |
+| `skeleton` | `boolean` | `true` | 冷启（首次无数据）网格卡片骨架 |
+| `skeletonRows` | `number` | 自适应 | 骨架卡片数 |
+| `initialSearch` | `boolean` | `true` | 挂载后是否立即触发初始化查询；false 时挂载不自动拉数（欢迎空态） |
+| `showToolbar` | `boolean` | `true` | toolbar 顶层开关 |
+| `toolbar` | `TableToolbarConfig<T,SQ,F>` | — | toolbar 配置（按钮 / 刷新 / 自动刷新 / 导出） |
+| `infiniteListProps` | `InfiniteListViewConfig` | — | InfiniteListView 配置透传（distance/endText/errorText/pullRefresh/estimateSize/overscan） |
+
+**v-model**：`isAutoRefresh`（boolean）、`refreshInterval`（number，秒）。
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `pageChange` | `number` | **拉取下一页时触发**（载荷 = 新页码） |
+| `dataChange` | `T[]` | 存量数组变更 |
+| `loadingChange` | `boolean` | 加载态变化 |
+| `pageInfoChange` | `TablePageInfo` | 存量信息：`{pageSize, currentPage, total}`——**`currentPage` = 当前已最大拉取到第几页**（非"第几页数据"）；复用 TableMain 形状，ListLayout 转发零改动 |
+| `pageSizeChange` | — | **不触发**（批次大小固定，运行期不改） |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#custom-view-item` | `DataListViewItemScope<T>`：`{fieldComponentMap, row, index, selected, toggleSelect}` | 网格卡片渲染；**缺省基于 columns 渲染朴素卡片**（每列 `label: value`，render 走 render / 非 render 走 `row[prop]`，`$type_selection` 勾选 / `$type_index` 序号） |
+| `empty`（内部默认） | 无 | 空数据——默认按 `hasRequested` 双态（未调用过 api → 欢迎触发查询；已调用无数据 → ElEmpty「暂无数据」） |
+
+### Expose（`DataGridViewInstance`）
+
+`refresh(silent?: boolean): Promise<unknown>`（清空存量重拉第 1 页）、`reload(silent?: boolean): Promise<unknown>`（回第 1 页重拉，同 refresh）、`getTableInstance(): TableInstance | undefined`（虚拟网格实例——选中/滚动能力对齐 TableInstance 子集，未实现方法为「not supported」抛错桩）。
+
+## 反模式 / 注意
+
+- **非分页形态**：[MUST NOT] 期待分页器 / 页码跳转；数据到底即停，无"下一页"按钮
+- **批次固定**：`pageSizeInit` 运行期不改；`pageSizeChange` 不触发
+- **`currentPage` 语义**：`pageInfoChange` 的 `currentPage` = 已拉最大页，消费方勿当"当前展示第几页"
+- **动态切换**：`viewMode` 换载（v-if）天然回到第 1 页重新累加；「翻到底再切网格续拉断点」不在支持范围
+- **独立使用成本**：不传 `toolbar`/搜索区时只有网格本体；完整列表页 [MUST] 走 `ListLayout`（搜索/头部/操作/粘性共享）
+- **列插槽无 `#<column.prop>`**：网格卡片是"一卡多列"形态，非表格"一列一格"；卡片渲染走 `#custom-view-item` 或默认 column 配置
+
+## 关联
+
+- 门面：`ListLayout`（`viewMode="grid"`；`viewMode="table"` 渲染 TableMain，内部 customView 切 ElTable/DataListView）
+- 底座：`InfiniteListView`（内部复用：IO 哨兵 + 虚拟化 + 底部三态）
+- 共享 hook：`useDataViewFieldMap`（列 → 稳定字段组件，与 DataListView 同源）
+- 工具栏：`TableToolbar`（table 族内部件，经 `toolbar` prop 配置）
+- 列表接口模型：`APP_API_LIST_MODEL_KEY_CONFIG`（core config 单源）
+- 范式页：`apps/reference/src/pages/data-view/grid/`

package/src/components/data-view/docs/README-InfiniteListView.md

@@ -0,0 +1,105 @@
+# InfiniteListView（通用无限滚动容器）
+
+> 受控无限滚动 + 虚拟列表容器：**不自持数据获取**——接收存量数据 + 加载状态，滚动到底触发 `load-more`，底部按状态渲染（加载中 / 错误+手动重试 / 到底提示）。
+> 通用原语：不依赖 table / list-layout 语境，任何「存量 + 无限滚动 + 虚拟列表」场景独立使用（纯列表流、聊天流、网格底座等）。
+> 范式页：`apps/reference/src/pages/data-view/grid/`（经 DataGridView 组装的网格形态）
+> 类型：data-view 族公共组件（进 core 顶层 export）
+
+## 定位
+
+- **何时用**：需要「数据存量 + 滚动到底加载 + 虚拟列表渲染」的列表/流式场景；作为 `DataGridView` 的网格渲染底座
+- **何时不用**：分页形态用 `TableMain`；仅当前页数据渲染用 `DataListView`
+- **受控组件**：`data`（存量）与 `loading / loadingMore / error / finished`（状态）均由外部传入；滚动到底发 `load-more`，错误点击发 `retry`，下拉刷新发 `refresh`——**数据状态机由外部（通常是数据容器）持有，本组件只管滚动触发 + 状态展示 + 虚拟化**
+- 泛型 `<T>`：行/项数据类型
+- 虚拟化：`@tanstack/vue-virtual` 单轴虚拟化（动态高经 measureElement 自动测量），只渲染可见项
+
+## 快速上手（最小可用）
+
+```vue
+<InfiniteListView
+  :data="store"
+  item-key="id"
+  :loading="loading"
+  :loading-more="loadingMore"
+  :error="error"
+  :finished="finished"
+  @load-more="fetchNextPage"
+  @retry="fetchNextPage"
+>
+  <template #item="{ item, index }">
+    <div>{{ index }}: {{ item.name }}</div>
+  </template>
+</InfiniteListView>
+```
+
+**要点**：
+
+- `data` / `itemKey` 必传；滚动到底（哨兵进入视口）且非 loading/loadingMore/error/finished 时发 `load-more`
+- 错误态底部显示 `error` 内容 + 「点击重试」→ 发 `retry`；`finished` 时底部显示 `endText`（默认"我是有底线的"）
+- `#item` 缺省时兜底渲染 `JSON.stringify(item, null, 2)`——**仅调试兜底，生产必传 `#item`**
+
+## 能力边界 / 按需使用
+
+- **默认即够用：滚动触发 + 底部三态（加载/错误重试/到底）+ 虚拟化全内置**——只传 `data` / `itemKey` / 状态 + 监听 `load-more` 即得无限滚动列表。
+- `estimateSize`：默认 200px 预估行高，虚拟化按实际测量自动校准；项高差异大时可调小/调大优化滚动条精度。
+- `maxHeight`：默认 `undefined`（自然高度，撑开父容器）；限高滚动时传容器最大高（内部 `overflowY: auto`）。
+- `pullRefresh`：默认关；开启后支持触摸下拉刷新（touch 三事件 + 顶部刷入指示器）→ 发 `refresh`。桌面 Web 常规用外部刷新按钮/自动刷新，[MUST NOT] 依赖手势。
+- `#error` / `#end` / `#loading-more` 插槽可覆写底部各态默认渲染。
+- `#empty`：`data` 为空时显示（默认 `<el-empty />`）。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（泛型 `T` 行/项）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `data` | `T[]`（必传） | — | 存量数据（累加结果，外部持有） |
+| `itemKey` | `Extract<keyof T,string> \| ((item:T)=>string)`（必传） | — | 虚拟项唯一键 |
+| `loading` | `boolean` | `false` | 首次加载中（底部显示加载占位） |
+| `loadingMore` | `boolean` | `false` | 加载更多中（底部显示加载占位，禁止重复触发） |
+| `error` | `Error \| string \| null` | `null` | 错误信息；非空时底部显示错误 + 重试（发 `retry`，手动点击才重新加载） |
+| `finished` | `boolean` | `false` | 是否到底（hasMore=false）；true 时底部显示 `endText` |
+| `loadMoreDistance` | `number` | `100` | 哨兵提前量（px）：距容器底部此距离内即触发 `load-more` |
+| `endText` | `string` | `"我是有底线的"` | 到底提示文案 |
+| `errorText` | `string` | `"加载失败，点击重试"` | 错误重试文案 |
+| `estimateSize` | `number` | `200` | 虚拟项预估高（px），按实际测量自动校准 |
+| `overscan` | `number` | `5` | 视口外预渲染项数（防快速滚动白屏） |
+| `maxHeight` | `number` | `undefined` | 传入时容器限高滚动（内部 `overflowY: auto`） |
+| `pullRefresh` | `boolean` | `false` | opt-in 触摸下拉刷新（默认关；开启后 touch 手势触发 `refresh`） |
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `load-more` | 无 | 滚动到底（哨兵进入视口）且非 loading/loadingMore/error/finished 时触发 |
+| `retry` | 无 | 底部错误「点击重试」触发 |
+| `refresh` | 无 | 下拉刷新触发（仅 `pullRefresh` 开启时） |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#item` | `{ item: T, index: number }` | 单项渲染；缺省兜底 `JSON.stringify(item, null, 2)`（**仅调试用，生产必传**） |
+| `#error` | `{ error: Error \| string \| null, retry: () => void }` | 底部错误态（默认：errorText + 重试按钮） |
+| `#end` | 无 | 底部到底提示（默认：`endText`） |
+| `#loading-more` | 无 | 加载中占位（默认：loading 文案 + 图标） |
+| `#empty` | 无 | 空数据（默认 `<el-empty />`） |
+
+### Expose
+
+`scrollTo(index: number)`（滚动到第 index 项）、`reset()`（重置：清虚拟缓存 + 回顶）。
+
+## 反模式 / 注意
+
+- **受控组件不自持数据**：`data` / 状态均由外部传入，[MUST NOT] 期待组件内部取数；数据累加 / hasMore 判断是**数据容器**（如 DataGridView）的职责
+- **`#item` 缺省 JSON 是调试兜底**：生产 [MUST] 传 `#item`；JSON 兜底 [MUST NOT] 当正经渲染
+- **`pullRefresh` 默认关**：桌面 Web 无手势语境，[MUST NOT] 依赖下拉刷新手势；用刷新按钮/自动刷新
+- **触发防抖**：`load-more` 在 loading/loadingMore/error/finished 任一态下不触发——外部 [MUST] 及时置 loading/loadingMore 防重复请求
+
+## 关联
+
+- 数据容器：`DataGridView`（内部按 gridColumns chunk 行后喂本组件）
+- 宿主容器：`TableMain`（分页容器，内部衍生品 `DataListView` 渲染当前页）
+- 共享 hook：`useDataViewFieldMap`（列 → 稳定字段组件）
+- 范式页：`apps/reference/src/pages/data-view/grid/`

package/types/components/data-view/DataGridView.vue.d.ts

@@ -0,0 +1,40 @@
+import { TableMainInstance, TablePageInfo } from '../table';
+import { DataGridViewProps } from './types';
+declare const _default: <T extends Record<string, any>, SQ extends Record<string, any>, F extends Record<string, any>>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
+        readonly "onUpdate:isAutoRefresh"?: ((value: boolean) => any) | undefined;
+        readonly onLoadingChange?: ((value: boolean) => any) | undefined;
+        readonly "onUpdate:refreshInterval"?: ((value: number) => any) | undefined;
+        readonly onPageChange?: ((page: number) => any) | undefined;
+        readonly onPageSizeChange?: ((page: number) => any) | undefined;
+        readonly onDataChange?: ((payload: T[]) => any) | undefined;
+        readonly onPageInfoChange?: ((info: TablePageInfo) => any) | undefined;
+        readonly onSelectionChange?: ((payload: T[]) => any) | undefined;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onUpdate:isAutoRefresh" | "onLoadingChange" | "onUpdate:refreshInterval" | "onPageChange" | "onPageSizeChange" | "onDataChange" | "onPageInfoChange" | "onSelectionChange"> & ({
+        isAutoRefresh?: boolean;
+        refreshInterval?: number;
+    } & DataGridViewProps<T, SQ, F>) & Partial<{}>> & import('vue').PublicProps;
+    expose(exposed: import('vue').ShallowUnwrapRef<TableMainInstance>): void;
+    attrs: any;
+    slots: {
+        'custom-view-item'?(_: {
+            fieldComponentMap: Record<string, import('vue').Component>;
+            row: T;
+            index: number;
+            selected: boolean;
+            toggleSelect: () => void;
+        }): any;
+    };
+    emit: {
+        (e: "pageChange" | "pageSizeChange", page: number): void;
+        (e: "dataChange" | "selectionChange", payload: T[]): void;
+        (e: "loadingChange", value: boolean): void;
+        (e: "pageInfoChange", info: TablePageInfo): void;
+    } & (((evt: "update:isAutoRefresh", value: boolean) => void) & ((evt: "update:refreshInterval", value: number) => void));
+}>) => import('vue').VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+export default _default;
+type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/types/components/data-view/DataListView.vue.d.ts

@@ -1,4 +1,3 @@
-import { Component } from 'vue';
 import { DataListViewProps } from './types';
 declare const _default: <T extends Record<string, any>, F extends Record<string, any>>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
@@ -8,7 +7,7 @@ declare const _default: <T extends Record<string, any>, F extends Record<string,
     attrs: any;
     slots: {
         item?(_: {
-            fieldComponentMap: Record<string, Component>;
+            fieldComponentMap: Record<string, import('vue').Component>;
             row: T;
             index: number;
             selected: boolean;

package/types/components/data-view/InfiniteListView.vue.d.ts

@@ -0,0 +1,30 @@
+import { InfiniteListViewInstance, InfiniteListViewProps } from './types';
+declare const _default: <T extends Record<string, any>>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
+        readonly onRefresh?: (() => any) | undefined;
+        readonly onLoadMore?: (() => any) | undefined;
+        readonly onRetry?: (() => any) | undefined;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onRefresh" | "onLoadMore" | "onRetry"> & InfiniteListViewProps<T> & Partial<{}>> & import('vue').PublicProps;
+    expose(exposed: import('vue').ShallowUnwrapRef<InfiniteListViewInstance>): void;
+    attrs: any;
+    slots: {
+        item?(_: {
+            item: T;
+            index: number;
+        }): any;
+        'loading-more'?(_: {}): any;
+        error?(_: {
+            error: string | Error;
+            retry: () => void;
+        }): any;
+        end?(_: {}): any;
+        empty?(_: {}): any;
+    };
+    emit: (e: "loadMore" | "retry" | "refresh") => void;
+}>) => import('vue').VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+export default _default;
+type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/types/components/data-view/index.d.ts

@@ -1,8 +1,14 @@
 import { default as DataListView } from './DataListView.vue';
 import { default as DataListViewItem } from './DataListViewItem.vue';
+import { default as InfiniteListView } from './InfiniteListView.vue';
+import { default as DataGridView } from './DataGridView.vue';
 export * from './types';
+export { resolveGridColumnsByBreakpoint } from './utils';
 /**
- * data-view 是 table 的内部衍生品：仅供 TableMain 内部 import，
- * [MUST NOT] 对外导出 / 全局注册 / 提供 install 插件（不进 core 顶层 export）。
+ * data-view 数据视图族 index
+ * ---
+ * 公共组件（进 core 顶层 export）：InfiniteListView / DataGridView（由 core 顶层
+ * index.ts 具名 re-export，[MUST NOT] `export *` 整个族——会漏出内部衍生品）。
+ * 内部衍生品（仅本族/table 内部 import，[MUST NOT] 对外导出）：DataListView / DataListViewItem。
  */
-export { DataListView, DataListViewItem };
+export { DataListView, DataListViewItem, InfiniteListView, DataGridView };

package/types/components/data-view/types.d.ts

@@ -1,5 +1,14 @@
 import { Component } from 'vue';
-import { ElTableColumnProps, TableColumnDefaultScope, TableInstance } from '../table';
+import { Breakpoint } from '../../hooks';
+import { ElTableColumnProps, TableApiParams, TableApiResult, TableColumnDefaultScope, TableInstance, TablePageInfo, TableToolbarConfig } from '../table';
+/**
+ * 网格断点列数配置（el-col span 制 24 栅格，对齐 FormSearch layout 心智）
+ * ---
+ * 值 = 当前断点下的 span（24 栅格，值大 = 列少）：
+ * `{ xs: 24, sm: 12, md: 12, lg: 8, xl: 6 }` → 1 / 2 / 2 / 3 / 4 列。
+ * 未配置的断点回落 ≤ 当前断点最近一档（el-col 心智），全无则用全局 span。
+ */
+export type GridColumnsConfig = Partial<Record<Breakpoint, number>>;
 /**
  * DataListView 字段渲染作用域
  * ---
@@ -64,3 +73,118 @@ export interface DataListViewItemScope<T extends Record<string, any> = Record<st
     /** 翻转当前行选中态 */
     toggleSelect: () => void;
 }
+/** InfiniteListView 配置（经 DataGridView.infiniteListProps 透传） */
+export interface InfiniteListViewConfig {
+    /** 哨兵提前量（px）：距容器底部此距离内即触发 load-more */
+    loadMoreDistance?: number;
+    /** 到底提示文案 */
+    endText?: string;
+    /** 错误重试文案 */
+    errorText?: string;
+    /** 虚拟项预估高（px），按实际测量自动校准 */
+    estimateSize?: number;
+    /** 视口外预渲染项数 */
+    overscan?: number;
+    /** opt-in 触摸下拉刷新（默认关） */
+    pullRefresh?: boolean;
+}
+/**
+ * InfiniteListView props（受控无限滚动容器）
+ * ---
+ * 不自持数据获取：data 存量 + 加载状态均由外部传入；滚动到底发 load-more，
+ * 错误点击发 retry，下拉刷新发 refresh——数据状态机由外部（数据容器）持有。
+ */
+export interface InfiniteListViewProps<T extends Record<string, any> = Record<string, any>> {
+    /** 存量数据（累加结果，外部持有） */
+    data: T[];
+    /** 虚拟项唯一键：键名或函数 */
+    itemKey: Extract<keyof T, string> | ((item: T) => string);
+    /** 首次加载中（底部显示加载占位） */
+    loading?: boolean;
+    /** 加载更多中（底部显示加载占位，禁止重复触发） */
+    loadingMore?: boolean;
+    /** 错误信息；非空时底部显示错误 + 重试（发 retry，手动点击才重新加载） */
+    error?: Error | string | null;
+    /** 是否到底（hasMore=false）；true 时底部显示 endText */
+    finished?: boolean;
+    /** 哨兵提前量（px） */
+    loadMoreDistance?: number;
+    /** 到底提示文案 */
+    endText?: string;
+    /** 错误重试文案 */
+    errorText?: string;
+    /** 虚拟项预估高（px） */
+    estimateSize?: number;
+    /** 视口外预渲染项数 */
+    overscan?: number;
+    /** 传入时容器限高滚动（内部 overflowY: auto）；数字 = px，字符串 = CSS 长度（如 "100vh"） */
+    maxHeight?: number | string;
+    /** opt-in 触摸下拉刷新（默认关） */
+    pullRefresh?: boolean;
+}
+/** InfiniteListView 实例 */
+export interface InfiniteListViewInstance {
+    /** 滚动到第 index 项 */
+    scrollTo: (index: number) => void;
+    /** 重置：清虚拟缓存 + 回顶 */
+    reset: () => void;
+}
+/**
+ * DataGridView props（对齐 TableMain 主 props − 分页面 + 存量/滚动面）
+ * ---
+ * 自持存量累加状态机：api + query + fetchNextPage + hasMore；
+ * 内部按 gridColumns 把存量 chunk 成行喂 InfiniteListView 虚拟化。
+ */
+export interface DataGridViewProps<T extends Record<string, any>, SQ extends Record<string, any>, F extends Record<string, any>> {
+    /** 列表请求；params = query 深合并 page.page/page.pageSize（键名 APP_API_LIST_MODEL_KEY_CONFIG 定） */
+    api: (params: TableApiParams<SQ>) => Promise<TableApiResult<T>>;
+    /** 列配置数组（驱动默认卡片渲染） */
+    columns: ElTableColumnProps<T, F>[];
+    /** 行/卡唯一键 */
+    rowKey: Extract<keyof T, string> | ((row: T) => string);
+    /** 静态查询参数；变化时清空存量从第 1 页重新累加 */
+    query?: SQ;
+    /** 每批加载条数（批次固定，运行期不改） */
+    pageSizeInit?: number;
+    /**
+     * 网格列数：number = 定列数等宽网格（默认 4）；对象 = el-col span 制断点配置
+     * （24 栅格，如 `{ xs: 24, sm: 12, md: 8, lg: 6, xl: 4 }`，列数 = 24 / span）。
+     */
+    gridColumns?: number | GridColumnsConfig;
+    /**
+     * 数据区最大高度；与 refine 二选一作为高度基准。
+     * 数字 = px；字符串 = CSS 长度（默认 "100vh" = 满视口高，等价视口高度限高，
+     * 非 refine 缺省兜底杜绝无限顶开；显式传入数字/字符串则覆盖）。
+     */
+    maxHeight?: number | string;
+    /** 精细化布局：无显式 maxHeight 时按 viewport 高减工具栏/底部得出数据区高 */
+    refine?: boolean;
+    /** refine 模式预留高度减量 */
+    refineReduceHeight?: number;
+    /** 显式指定视口可用高（优先级最高） */
+    viewportHeight?: number;
+    /** 定向消费的祖先 scope 标识 */
+    parentChannel?: string;
+    /** 数据滚动区 min-height 撑满可用高、底部状态贴底 */
+    fillHeight?: boolean;
+    /** 数据视口最大高最小值 floor 兜底 */
+    dataViewMaxHeightMinValue?: number;
+    /** 注入列作用域/卡片作用域的额外对象 */
+    injectInfo?: F;
+    /** 冷启（首次无数据）网格卡片骨架 */
+    skeleton?: boolean;
+    /** 骨架卡片数 */
+    skeletonRows?: number;
+    /** 挂载后是否立即触发初始化查询；false 时挂载不自动拉数 */
+    initialSearch?: boolean;
+    /** toolbar 顶层开关 */
+    showToolbar?: boolean;
+    /** toolbar 配置（按钮 / 刷新 / 自动刷新 / 导出） */
+    toolbar?: TableToolbarConfig<T, SQ, F>;
+    /** InfiniteListView 配置透传 */
+    infiniteListProps?: InfiniteListViewConfig;
+}
+/** DataGridView 实例（选中/滚动能力对齐 TableInstance 子集，未实现抛错桩） */
+export type DataGridViewInstance = TableInstance;
+/** DataGridView 对外分页信息（复用 TablePageInfo：currentPage = 已拉最大页） */
+export type DataGridViewPageInfo = TablePageInfo;

package/types/components/data-view/use-data-view-field-map.d.ts

@@ -0,0 +1,24 @@
+import { Component, ComputedRef } from 'vue';
+import { TableColumnDefaultScope } from '../table';
+import { DataViewColumn } from './types';
+/**
+ * useDataViewFieldMap —— 列配置 → 稳定字段组件（data-view 族共享 hook）
+ * ---
+ * DataListView 与 DataGridView 同源构建 `fieldComponentMap`（列 key → 稳定字段组件），
+ * 防渲染层双线漂移。组件标识跨渲染稳定（markRaw + 闭包 column），
+ * data/选中变更只 patch props 不 remount。
+ */
+export interface UseDataViewFieldMapOptions<T extends Record<string, any> = Record<string, any>, F extends Record<string, any> = {}> {
+    /** 列配置 getter（响应式：随 columns 变化重建 map） */
+    columns: () => DataViewColumn<T>[];
+    /** 列 render 上下文（injectInfo + exposeInfo） */
+    getRenderCtxParams: () => Pick<TableColumnDefaultScope<T, F>, "injectInfo" | "exposeInfo">;
+}
+/**
+ * 列配置 → fieldComponentMap（computed）。
+ * 普通列 key=prop；type:index/selection → 保留键 $type_index/$type_selection；
+ * type:expand 不支持（跳过）。
+ */
+export declare function useDataViewFieldMap<T extends Record<string, any> = Record<string, any>, F extends Record<string, any> = {}>(options: UseDataViewFieldMapOptions<T, F>): {
+    fieldComponentMap: ComputedRef<Record<string, Component>>;
+};

package/types/components/data-view/use-pull-refresh.d.ts

@@ -0,0 +1,20 @@
+/**
+ * usePullRefresh —— InfiniteListView 的 opt-in 触摸下拉刷新（私有，不出桶）
+ * ---
+ * 桌面 Web 无手势语境默认关（规则：刷新走按钮/自动刷新）；H5/移动适配时开启。
+ * 仅当滚动容器在顶部（scrollTop === 0）才响应下拉；下拉超阈值释放 → onRefresh。
+ */
+export declare function usePullRefresh(options: {
+    /** 是否启用（pullRefresh prop） */
+    enabled: () => boolean;
+    /** 滚动容器 */
+    getScrollContainer: () => HTMLElement | null;
+    /** 释放刷新回调 */
+    onRefresh: () => void;
+}): {
+    pullDistance: import('vue').Ref<number, number>;
+    pullThreshold: number;
+    onTouchStart: (e: TouchEvent) => void;
+    onTouchMove: (e: TouchEvent) => void;
+    onTouchEnd: () => void;
+};

package/types/components/data-view/utils.d.ts

@@ -1,4 +1,16 @@
-import { DataListViewInstance } from './types';
+import { Breakpoint } from '../../hooks';
+import { DataListViewInstance, GridColumnsConfig } from './types';
+/**
+ * 网格断点列数配置 → 当前断点列数（el-col span 制 24 栅格换算）
+ * ---
+ * - number（定列数）→ 原样（clamp ≥ 1）
+ * - 对象 → 取 ≤ 当前断点最近一档的 span（未配回落更小档，全无回落 24 = 1 列），列数 = 24 / span
+ * - span 非法（≤ 0 / NaN）→ 兜底 24（1 列）
+ */
+export declare const resolveGridColumnsByBreakpoint: (gridColumns: number | GridColumnsConfig | undefined, breakpoint: Breakpoint) => number;
+/**
+ * 创建 DataListView 实例
+ */
 /**
  * 创建 DataListView 实例
  */

package/types/components/list-layout/ListLayout.vue.d.ts

@@ -35,6 +35,10 @@ declare const _default: <T extends Record<string, any>, PO extends Record<string
         pagerSticky?: boolean;
         headerObserveResize?: boolean;
         operationObserveResize?: boolean;
+        viewMode?: "table" | "grid";
+        gridColumns?: number | import('../data-view').GridColumnsConfig;
+        infiniteListProps?: import('../data-view').InfiniteListViewConfig;
+        gridProps?: Partial<Omit<import('../data-view').DataGridViewProps<T, import('../form').ExcludeNeverProperties<import('../form').ExtractFormStringifyRawFromObject<PO, SO>> & SQ, ListLayoutInnerInjectInfo<PO, F>>, "toolbar" | "refine" | "gridColumns" | "infiniteListProps" | import('./types').TableMainRequiredKey | import('./types').TableMainRewriteKey>> | undefined;
     }) & Partial<{}>> & import('vue').PublicProps;
     expose(exposed: import('vue').ShallowUnwrapRef<ListLayoutInstance<PO, Record<string, any>>>): void;
     attrs: any;

package/types/components/list-layout/types.d.ts

@@ -1,6 +1,7 @@
 import { ExtractFormStringifyFromObject, ExtractFormStringifyFromList, FormItemConfigList, FormSearchInstance, FormSearchProps, FormSearchSearchType } from '../form';
 import { TableApiParams, TableApiResult, TableMainInstance, TableMainProps } from '../table';
 import { SlotLayoutFlowAsideProps } from '../slot-layout';
+import { DataGridViewProps, GridColumnsConfig, InfiniteListViewConfig } from '../data-view';
 export type FormSearchOptionsKey = "staticQuery";
 export type FormSearchRewriteKey = "list";
 export type TableMainOptionsKey = "refine" | "refineReduceHeight" | "viewportHeight" | "parentChannel" | "toolbar" | "showSwitchView";
@@ -88,6 +89,21 @@ F extends Record<string, any>> = Partial<Pick<FormSearchProps<PO, SO, {}>, FormS
     headerObserveResize?: boolean;
     /** operation 插槽量高是否启用 ResizeObserver（语义同 headerObserveResize，默认 false）。 */
     operationObserveResize?: boolean;
+    /**
+     * 数据展示载体：table（默认，TableMain 分页容器，内部可再经 customView 切 DataListView）/
+     * grid（DataGridView 存量累加网格，无限滚动）。初始化定好、运行期不改。
+     */
+    viewMode?: "table" | "grid";
+    /**
+     * 网格列数（仅 viewMode="grid" 生效，默认 4）：number = 定列数等宽网格；
+     * 对象 = el-col span 制断点配置（24 栅格，如 `{ xs: 24, sm: 12, md: 8, lg: 6, xl: 4 }`，
+     * 列数 = 24 / span，对齐 FormSearch layout 心智）。
+     */
+    gridColumns?: number | GridColumnsConfig;
+    /** InfiniteListView 配置透传（仅 viewMode="grid" 生效）。 */
+    infiniteListProps?: InfiniteListViewConfig;
+    /** DataGridView 其余配置透传（仅 viewMode="grid" 生效，对齐 tableMainProps 模式）。 */
+    gridProps?: Partial<Omit<DataGridViewProps<T, ExtractFormStringifyFromObject<PO, SO> & SQ, ListLayoutInnerInjectInfo<PO, F>>, TableMainRequiredKey | TableMainRewriteKey | "refine" | "toolbar" | "gridColumns" | "infiniteListProps">>;
 };
 export interface ListLayoutInstance<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>> extends FormSearchInstance<PO, SO>, TableMainInstance {
     /** 更新表单数据 */

package/types/components/table/index.d.ts

@@ -1,4 +1,14 @@
 import { default as TableMain } from './TableMain.vue';
+import { default as TableToolbar } from './TableToolbar.vue';
+import { default as TableEmpty } from './TableEmpty.vue';
+import { default as TableSkeleton } from './TableSkeleton.vue';
 export * from './types';
 export * from './constants';
-export { TableMain };
+/**
+ * table 族 index
+ * ---
+ * 公开组件：TableMain（数据表格容器）；TableToolbar / TableEmpty / TableSkeleton
+ * 为跨容器复用件（TableMain 与 data-view 族 DataGridView 共用，空态/骨架/工具栏
+ * 视觉两容器一致防漂移）。ToolbarButtons 保持内部件（[MUST NOT] 外部消费）。
+ */
+export { TableMain, TableToolbar, TableEmpty, TableSkeleton };

package/types/index.d.ts

@@ -1,4 +1,6 @@
 export * from './components/form';
+export { InfiniteListView, DataGridView } from './components/data-view';
+export type { DataGridViewInstance, DataGridViewPageInfo, DataGridViewProps, InfiniteListViewConfig, InfiniteListViewInstance, InfiniteListViewProps, } from './components/data-view';
 export * from './components/menu';
 export * from './components/display';
 export * from './components/misc';

package/types/injectInfo.json.d.ts

@@ -1,6 +1,6 @@
 declare const _default: {
   "name": "@done-coding/admin-core",
-  "version": "0.22.2",
+  "version": "0.22.3-alpha.0",
   "description": "内部前端库"
 };