@xrubik/fabric-to-leafer 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rubik
+
+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,63 @@
-# Temporary Holding Version
+# @rubik/fabric-to-leafer
 
-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.
+Fabric JSON → Leafer JSON 转换器。纯数据转换，不依赖 `leafer-ui`，可在浏览器、Node、Worker、CLI 中运行。
+
+```js
+import { convert, convertSync } from '@rubik/fabric-to-leafer'
+
+const { document, warnings } = await convert(fabricJson, {
+  resolveAsset: (path) => '/assets/' + path,
+  // lib 只保存 libName 时，由宿主提供页面定义
+  loadLib: (libName) => fetch('/mmi/' + libName + '.json').then((res) => res.json())
+})
+```
+
+反向转换（Leafer JSON → Fabric JSON），返回结构和 `convertSync` 一致：
+
+```js
+import { convertSync, leaferToFabric } from '@rubik/fabric-to-leafer'
+
+const { document: leafer } = convertSync(fabricJson)
+const { document: fabric, warnings } = leaferToFabric(leafer, { version: '5.5.2' })
+```
+
+## 结构
+
+```text
+src/
+  convert.js        主流程：遍历 objects → children
+  context.js        配置、告警、资源解析
+  document.js       根文档 header / param
+  nodes.js          纯对象节点工厂
+  colors.js         颜色归一化
+  gradient.js       渐变转换
+  pattern.js        Pattern 填充/描边 → Leafer 图片 paint
+  geometry.js       定位、翻转、点集、path 字符串
+  assets.js         图片地址 → resolveAsset
+  lib.js            lib 参数替换、页面动作清理、lib 引用水合 / 剥离
+  leafer2fabric.js  Leafer JSON → Fabric JSON（反向转换）
+  elements/         每种 Fabric 类型一个文件
+  attributes/       公共属性：变换 / 填充 / 文本 / 元数据
+```
+
+## 加一种元素
+
+1. 新建 `src/elements/xxx.js`，导出 `convertXxx(object, ctx, parent)`
+2. 在 `src/elements/index.js` 的类型表里登记
+
+## 加一个公共属性
+
+放到 `src/attributes/` 对应文件，由 `applyCommon` 统一调用，不要写进各个元素。
+
+## 与 leafer-ui 配合
+
+应用启动时注册一次自定义字段，否则 `toJSON()` / 保存时 `type`、`param`、`action` 会被丢掉：
+
+```js
+import { registerFabricAttrs } from '@rubik/fabric-to-leafer/leafer'
+registerFabricAttrs()
+```
+
+- 已有 JSON：`leafer.add(document.children)`
+- 需要节点实例：`const { children } = await convertToNodes(fabricJson)`
+- lib 会输出 `tag: 'Lib'` 自定义元素，实例化前需要先导入 `@rubik/fabric-to-leafer-elements`