z-paging-wevu 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 littleturtle2333
+Copyright (c) 2021 zxlee
+
+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

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# z-paging-wevu
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+面向 **weapp-vite + wevu + Vue SFC** 的 z-paging 兼容实现。保留 z-paging 的分页心智模型，同时针对微信小程序运行时处理事件参数、虚拟列表和布局差异。
+
+> 当前版本为 0.1.0，目标是微信小程序；nvue 专属渲染仅保留兼容入口。
+
+## 能力
+
+- 自动分页、下拉刷新、触底或点击加载更多
+- `complete` / `completeByKey` / `completeByTotal` / `completeByNoMore`
+- 内置 `fetch`、本地分页、缓存、空态与加载失败
+- 页面滚动、整屏 `scroll-view`、顶部/底部/左右插槽
+- 固定和动态高度虚拟列表、聊天记录模式、键盘适配
+- 自定义下拉刷新、二楼 F2、返回顶部、国际化文本
+- TypeScript 类型与 `createPagingController()` 控制器
+
+## 安装
+
+```bash
+pnpm add z-paging-wevu wevu
+```
+
+也可以直接将 `src/components/z-paging-wevu/` 复制到项目的组件目录。
+
+## 快速开始
+
+```vue
+<script setup lang="ts">
+import { ref } from 'wevu'
+import ZPagingWevu, { createPagingController } from 'z-paging-wevu'
+
+const items = ref<Record<string, unknown>[]>([])
+const paging = createPagingController()
+
+async function queryList([pageNo, pageSize]: [number, number, string]) {
+  const result = await fetchYourPage({ pageNo, pageSize })
+  await paging.complete(result)
+}
+</script>
+
+<template>
+  <ZPagingWevu
+    v-model="items"
+    :controller="paging"
+    paging-data-key="order-list"
+    @query="queryList"
+  >
+    <view v-for="item in items" :key="String(item.id)">
+      {{ item.title }}
+    </view>
+  </ZPagingWevu>
+</template>
+```
+
+**注意：** wevu 自定义组件的多参数事件会合并为数组，因此 `@query` 的参数是一个数组。请求结束后必须调用 `complete` 系列方法；刷新列表使用 `reload()`，不要手动调用内部查询流程。
+
+## 文档
+
+在线文档：<https://littleturtle2333.github.io/z-paging-wevu/>
+
+```bash
+pnpm install
+pnpm dev
+```
+
+构建组件类型检查与文档站：
+
+```bash
+pnpm build
+```
+
+文档覆盖安装、两种滚动模式、Props / Methods / Events / Slots，以及虚拟列表、聊天、本地分页、缓存和迁移注意事项。
+
+真实浏览器验收（首次运行需要安装 Chromium）：
+
+```bash
+pnpm exec playwright install chromium
+pnpm test:docs
+```
+
+验收脚本会临时启动文档服务，检查主要导航、主题切换、移动端横向溢出、控制台错误和失败请求，并在结束时关闭服务与浏览器。
+
+## 与 z-paging 的主要差异
+
+- 微信中使用 `paging-data-key`，避免原生 `data-*` 属性冲突。
+- 微信虚拟列表推荐 `force-close-inner-list` + `@virtual-list-change` + 页面 `v-for`。
+- 每个虚拟列表 cell 的 DOM id 必须为 `zp-id-${item.zp_index}`。
+- 聊天消息项需要设置 `transform: scaleY(-1)` 恢复内容方向。
+- `withDefaults` 默认值保留在 SFC 内，避免 wevu 不支持的 `mergeDefaults` 辅助函数。
+
+## 致谢与许可
+
+本项目是 [SmileZXLee/uni-z-paging](https://github.com/SmileZXLee/uni-z-paging) 的独立兼容实现，API 与文档组织参考了原项目及其文档仓库。原项目采用 MIT 许可证；相关版权声明保留在 [LICENSE](./LICENSE) 中。
+
+本项目同样采用 MIT 许可证。

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "z-paging-wevu",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "面向 weapp-vite + wevu 的 z-paging 兼容分页组件",
+  "type": "module",
+  "license": "MIT",
+  "author": "littleturtle2333",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LittleTurtle2333/z-paging-wevu.git"
+  },
+  "homepage": "https://littleturtle2333.github.io/z-paging-wevu/",
+  "bugs": {
+    "url": "https://github.com/LittleTurtle2333/z-paging-wevu/issues"
+  },
+  "keywords": [
+    "z-paging",
+    "weapp-vite",
+    "wevu",
+    "miniprogram",
+    "pagination",
+    "virtual-list"
+  ],
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./component": "./src/components/z-paging-wevu/index.vue",
+    "./controller": {
+      "types": "./src/components/z-paging-wevu/types.ts",
+      "default": "./src/components/z-paging-wevu/types.ts"
+    },
+    "./props": {
+      "types": "./src/components/z-paging-wevu/props.ts",
+      "default": "./src/components/z-paging-wevu/props.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "**/*.vue",
+    "**/*.css"
+  ],
+  "scripts": {
+    "dev": "vitepress dev docs",
+    "dev:docs": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json",
+    "test:docs": "node scripts/verify-docs.mjs",
+    "build": "pnpm typecheck && pnpm docs:build"
+  },
+  "peerDependencies": {
+    "wevu": ">=7.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "miniprogram-api-typings": "^5.2.3",
+    "playwright": "^1.64.1",
+    "typescript": "^6.0.3",
+    "vitepress": "^1.6.4",
+    "vue": "^3.5.13",
+    "vue-tsc": "^3.3.12",
+    "wevu": "^7.5.0"
+  },
+  "engines": {
+    "node": ">=20.19.0",
+    "pnpm": ">=9"
+  },
+  "packageManager": "pnpm@11.20.0"
+}