@melt-js/libs-react-leva 0.0.0-stage → 2026.11.13

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# @melt-js/libs-react-leva
 
-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.
+React 的属性面板（Leva）：`PropsPlayground` + `PropsPanel` + schema 生成 CLI，同时是一个 hel 远程包。
+
+- **自包含**：面板组件、schema 生成脚本都在本包内，和 `libs-vue3-leva` 各自独立维护（两边 schema 形状同构，面板控件库不同：Vue 版用 tweakpane，React 版用 Leva）
+- **不认任何具体组件**：组件映射和 schema 都由宿主传进来
+- **schema 由脚本从 TS 源码生成**：`react-docgen-typescript` 解析组件 props 的 interface / type 与 JSDoc，输出到组件目录旁边
+
+## 远程使用
+
+宿主页面需先把 React 运行时绑定到全局，远程包与宿主共用同一份 React，否则会触发 invalid hook call：
+
+```ts
+import helMicro from 'hel-micro'
+helMicro.bindReactRuntime({ React, ReactDOM, ReactIs })
+```
+
+`react` / `react-dom` / `react-is` 均为 peer 依赖，不打进本包：
+
+- 生产产物（rollup UMD）按 external + UMD globals 映射到全局 `React` / `ReactDOM` / `ReactIs`
+- dev 下 vite 会把裸依赖预打包进自己的 deps chunk，易形成第二份 React；本包用 `src/shims/*` 在 dev 阶段把 react 系列 alias 到全局运行时（仅 serve 生效，build 不经过）
+
+```bash
+pnpm libs-react-leva:dev     # 10050，直接打开是本包调试页
+pnpm libs-react-leva:build   # 发布用产物，资源地址指向 unpkg
+```
+
+```ts
+import { preFetchLib } from 'hel-micro'
+await preFetchLib('libs-react-leva', { custom: { host: 'http://localhost:10050', skipFetchHelMeta: true } })
+
+// 路由懒加载的页面里（此时已预加载完成）取组件
+const { PropsPlayground } = await import('@melt-js/libs-react-leva')
+```
+
+```tsx
+<PropsPlayground
+  components={components}
+  schemas={schemas}
+  presets={presets}
+  listeners={listeners}
+  stageClasses={stageClasses}
+  stageStyles={stageStyles}
+  slotHtml={slotHtml}
+/>
+```
+
+- `components`：`{ 组件名: 组件 }`
+- `schemas`：`{ 组件名: propsSchema.json 的内容 }`
+- `presets`：可选，`{ 组件名: { items: [...] } }`，面板不生成控件的复杂 props / 配套数据；同时会作为面板的初始值
+- `listeners`：可选，`{ 组件名: { select: (item) => ... } }`，透传给组件的事件回调（`select` 会映射成 `onSelect`）
+- `stageClasses` / `stageStyles`：可选，`{ 组件名: 'is-dark' }` / `{ 组件名: { height: '480px' } }`
+- `slotHtml`：可选，`{ 组件名: { default: '<p>内容</p>' } }`，当前 `default` 作为 children 填充
+
+`PropsPanel` 也可以单独用：`schema` + 受控 `value` / `onChange`。
+
+## 发布 npm / unpkg
+
+在本包目录执行 `pnpm run publish:stage`，或在仓库根目录执行 `pnpm libs-react-leva:publish:stage`。命令先构建 HEL 产物并校验版本、资源地址及包入口，再通过共享发布脚本打包并提交 npm stage。
+
+完成 npm 发布后，入口为 `https://unpkg.com/@melt-js/libs-react-leva@<version>/hel_dist/index.html`，远程加载使用同目录的 `hel-meta.json`。
+
+## schema 生成
+
+组件包（如 `comps-react`）用 `workspace:*` 引本包，把 `gen:schema` 指向 CLI：
+
+```json
+{
+  "dependencies": { "@melt-js/libs-react-leva": "workspace:*" },
+  "scripts": { "gen:schema": "react-leva-gen-schema" }
+}
+```
+
+组件包根目录放 `playground.config.mjs`：
+
+```js
+export default {
+  components: [
+    { name: 'HelloButton', file: 'src/components/HelloButton.tsx' },
+  ],
+  hints: { HelloButton: { size: { min: 12, max: 48, step: 1 } } },
+}
+```
+
+```bash
+react-leva-gen-schema          # 生成 / 更新 propsSchema.json
+react-leva-gen-schema --check  # CI：schema 与源码不一致时退出码 1
+```
+
+约定：
+
+- props 用 `interface Props` / `type Props` 声明，属性上方的 JSDoc 作为 `description`
+- `index.tsx` 写到同目录 `propsSchema.json`，单文件组件写 `Foo.propsSchema.json`
+- 字符串字面量联合（`'a' | 'b'`）会生成下拉 `options`
+- `onXxx` 或 `function` 类型的 prop 标记为事件，不生成控件；对象 / 数组等复杂类型走 `presets` 固定传入
+
+## schema 条目形状
+
+```json
+{
+  "name": "variant",
+  "type": "'rounded' | 'block'",
+  "description": "形态：rounded 圆角按钮，block 块状按钮",
+  "default": "\"rounded\"",
+  "required": false,
+  "version": "",
+  "isEvent": false,
+  "bindable": true,
+  "value": "rounded",
+  "control": { "options": { "rounded": "rounded", "block": "block" } }
+}
+```
+
+- `bindable`：`boolean` / `number` / `string` 才生成控件
+- `value`：可绑定 prop 的面板初始值（已从默认值表达式转成字面量）
+- `control`：原样交给 Leva 的控件配置（`min` / `max` / `step` / `options` 等）