@worm-vue3-print/common 0.0.0-stage → 1.3.7-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+
+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,100 @@
-# Temporary Holding Version
+# @worm-vue3-print/common
 
-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.
+> ⚠️ **实验性质 · 以预览版发布到 npm**：dist-tag 为 `next`，安装必须写 `@worm-vue3-print/common@next`；
+> 版本号形如 `1.3.7-beta.N`（与主线同号 + 预发布后缀）。npm 上还没有 `latest`，转正时才发 stable。
+> 本包尚未定版，接口与产物形态仍可能调整，**不建议应用到生产环境**；
+> Vue 3 项目请使用成熟方案 `@worm-vue3-print/canvas`，本包目前仅供评估与非生产环境的集成验证。
+
+打印模板可视化设计器的 **通用宿主适配形态**：任意框架、或完全没有框架的宿主都能直接接入，
+实现为零框架原生 Custom Element + Shadow DOM，**不依赖 Vue / React 等任何框架运行时**，
+用于把 `@worm-vue3-print/canvas`（Vue 3 版设计器）的能力带给 Vue 2、React、jQuery 及任意非 Vue3 宿主。
+
+- 功能与布局与 Vue 3 版对齐，逐项状态见 [PARITY.md](./PARITY.md)
+- 样式与图标从 canvas 构建产物**派生**（`scripts/gen-styles.mjs` 剥离 `[data-v-*]`、
+  `scripts/gen-icons.mjs` 抽取 lucide 图标），因此 canvas 改版后重新构建即自动跟随
+- 运行时体积：`dist/index.js` 348.14 kB（gzip 99.99 kB），零框架依赖
+- 浏览器直挂形态：`dist/common.js`（UMD，core 与码制库已内联）+ `dist/common.css`，见下节
+
+## 安装
+
+```bash
+npm i @worm-vue3-print/common@next @worm-vue3-print/core
+```
+
+`@next` 是预览版的 dist-tag，省略会报 `No matching version found`（stable 还没发，npm 上不存在 `latest`）。
+`core` 装正式版即可（本包依赖 `^1.3.7`），出纸链路也要直接用它。
+
+## 浏览器直挂（jQuery / 无打包器宿主）
+
+`vite.bundle.config.ts` 额外产出两个文件，子路径 `@worm-vue3-print/common/browser` 指向它们：
+
+- `dist/common.js`（474.96 kB / gzip 145.34 kB）：UMD，把 `@worm-vue3-print/core` 与条形码、二维码库
+  全部内联，并挂出全局 `window.WormPrintCommon`。除了本包 `index` 的那套 API
+  （`registerAll` / `createDefaultTemplate` / `DesignerStore` / `PrintDesignerElement`），
+  还一并挂出出纸要用的 `renderHtmlPages` / `browserCodeRenderer` / `PrintClient` / `WormPrintError`，
+  以及宿主自绘模板缩略图所需的纸张几何工具 `getPaperDimensions` / `isContinuousPaperSize` / `getByPath`
+  —— 直挂宿主拿不到裸包名 `@worm-vue3-print/core`，没有这些入口就无法在同一个 `<script>` 里
+  完成「浏览器渲染 → 打印 / 静默打印」
+- `dist/common.css`：即 `src/styles/designer.css`（由 `gen-styles.mjs` 从 canvas 派生，含 `:host` 块级基线）。
+  Shadow DOM 形态用不到它——样式由组件内联注入；只有把设计器渲染进 **light DOM** 时才需要引它，
+  公开子路径为 `@worm-vue3-print/common/style.css`（打包器 `import '@worm-vue3-print/common/style.css'`，
+  无打包器则复制成文件后 `<link>`），不要深路径引 `dist/`
+
+```html
+<link rel="stylesheet" href="/vendor/worm-print-common.css" />
+<script src="/vendor/worm-print-common.js"></script>
+<script>
+  WormPrintCommon.registerAll()
+  const el = document.querySelector('print-designer')
+  el.fields = fields                 // 数组/对象只能赋 property
+  el.template = templateJson
+  el.uploadImage = file => uploadToServer(file)
+  el.addEventListener('save', e => persist(e.detail))
+  const out = await WormPrintCommon.renderHtmlPages(
+    JSON.parse(el.getTemplateJson()), data, location.origin, WormPrintCommon.browserCodeRenderer)
+</script>
+```
+
+两个硬约束：自定义元素默认 `display:inline`，宿主必须给它块级宽高，否则设计器整体塌陷；
+`fields` 没有 getter，读回要看 `el.store.fields`。
+
+完整可运行的直挂宿主示例见 `demo-common/apps/jquery`（含 `sync-assets.mjs` 如何从包 dist 取这两个文件、
+以及 `/render-api` 透传的 40 行静态服务器）；Vue3 / Vue2 / React 三种 NPM 接入形态见
+`demo-common/apps/vue3`、`demo-common/apps/vue2`、`demo-common/apps/react`。
+
+## 使用
+
+```js
+import { registerAll } from '@worm-vue3-print/common'
+registerAll()   // 注册 <print-designer>，按需调用，不自动污染全局
+```
+
+```html
+<print-designer id="d" style="height:100%"></print-designer>
+```
+
+```js
+const d = document.getElementById('d')
+d.fields = [{ fieldKey: 'orderNo', fieldLabel: '单号' }]   // 也接受 JSON 字符串
+d.template = templateJson
+d.addEventListener('save', e => save(e.detail))            // e.detail 为模板 JSON
+d.addEventListener('preview', e => preview(e.detail))
+d.getTemplateJson()
+d.validateTemplate()      // 拼版/多页配置校验，宿主旁路导出前调用
+d.loadTemplate(json)
+d.save()
+```
+
+出纸链路不需要设计器，直接走 `@worm-vue3-print/core`（浏览器渲染 / print-render 服务端 /
+桌面静默打印），与 canvas（Vue 3）宿主完全一致。
+
+## 与 canvas 版的边界
+
+| | canvas（Vue 3） | common（本包） |
+|---|---|---|
+| 运行时 | Vue 3.5 | 无框架 |
+| 宿主注入 | `provide/inject`、props | element property / attribute + CustomEvent |
+| 样式 | `@worm-vue3-print/canvas/style.css` | 内置 Shadow DOM（`?inline`），无需引样式文件；light DOM 形态引 `@worm-vue3-print/common/style.css` |
+| 适用 | Vue 3 项目 | React / Vue 2 / jQuery / 原生 |
+
+Vue 3 项目应继续用 `@worm-vue3-print/canvas`，功能面更全；本包面向非 Vue3 宿主。

package/dist/browser-bundle.d.ts

@@ -0,0 +1,12 @@
+/*!
+ * @worm-vue3-print/common v1.3.7-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+import { getPaperDimensions, isContinuousPaperSize, getByPath } from '@worm-vue3-print/core';
+import { renderHtmlPages, browserCodeRenderer } from '@worm-vue3-print/core/browser';
+import { PrintClient, WormPrintError } from '@worm-vue3-print/core/client';
+export * from './index';
+export { renderHtmlPages, browserCodeRenderer, PrintClient, WormPrintError };
+export { getPaperDimensions, isContinuousPaperSize, getByPath };