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

package/src/PropsPanel.tsx

@@ -0,0 +1,60 @@
+import React, { useEffect, useMemo } from 'react'
+import { LevaPanel, useControls, useCreateStore } from 'leva'
+import type { PropSchema } from './core/schema'
+import { complexPropNames } from './core/schema'
+import { toLevaSchema } from './core/leva'
+
+export interface PropsPanelProps {
+  /** 面板分组名，一般传组件名 */
+  compName?: string
+  /** 组件的 propsSchema.json 内容 */
+  schema: PropSchema[]
+  /** 受控用法：外部持有的值对象（仅作为初始值，面板改动通过 onChange 回传） */
+  value?: Record<string, unknown>
+  /** 控件改动回调，回传整份最新值 */
+  onChange?: (next: Record<string, unknown>) => void
+  /** 根节点附加 class */
+  className?: string
+}
+
+/**
+ * 通用的 props 属性面板：只认 schema，不关心是哪个组件。
+ *
+ * 与 Vue 版 PropsPanel 同构：schema 决定生成哪些控件，控件值由 Leva store 持有，
+ * 改完通过 onChange 通知父级；复杂类型（对象 / 数组 / 事件）不生成控件，只给提示。
+ */
+export default function PropsPanel({
+  compName,
+  schema,
+  value,
+  onChange,
+  className,
+}: PropsPanelProps) {
+  const levaSchema = useMemo(() => toLevaSchema(schema, value), [schema, value])
+  const complex = useMemo(() => complexPropNames(schema), [schema])
+
+  // 每个面板持有独立 store，组件切换或多个面板共存时，同名属性不会串值。
+  const store = useCreateStore()
+  const levaValues = useControls(levaSchema, { store })
+
+  // 面板值变化 -> 通知父级
+  useEffect(() => {
+    onChange?.(levaValues as Record<string, unknown>)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [levaValues])
+
+  return (
+    <div className={`props-panel${className ? ` ${className}` : ''}`}>
+      <LevaPanel
+        store={store}
+        fill
+        flat
+        hideCopyButton
+        titleBar={{ title: compName || '属性面板', drag: false, filter: false }}
+      />
+      {complex.length > 0 && (
+        <p className="props-panel__hint">复杂类型暂未生成控件：{complex.join('、')}</p>
+      )}
+    </div>
+  )
+}

package/src/PropsPlayground.tsx

@@ -0,0 +1,152 @@
+import React, { useEffect, useMemo, useState } from 'react'
+import PropsPanel from './PropsPanel'
+import type { PropSchema } from './core/schema'
+import { createValues } from './core/schema'
+
+type Listener = (...args: unknown[]) => void
+
+export interface PropsPlaygroundProps {
+  /** { 组件名: 组件 } */
+  components: Record<string, React.ComponentType<Record<string, unknown>>>
+  /** { 组件名: propsSchema 数组 } */
+  schemas: Record<string, PropSchema[]>
+  /** 可选：{ 组件名: { items: [...] } }，面板不生成控件的复杂 props / 配套数据，同时覆盖初始值 */
+  presets?: Record<string, Record<string, unknown>>
+  /** 可选：{ 组件名: { select: (item) => ... } }，组件事件监听 */
+  listeners?: Record<string, Record<string, Listener>>
+  /** 可选：{ 组件名: 'is-dark' }，预览舞台附加 class */
+  stageClasses?: Record<string, string>
+  /** 可选：{ 组件名: { height: '480px' } }，预览舞台内联样式 */
+  stageStyles?: Record<string, React.CSSProperties>
+  /** 可选：{ 组件名: { default: '<p>内容</p>' } }，插槽用 HTML 字符串填充（当前支持 default 作为 children） */
+  slotHtml?: Record<string, Record<string, string>>
+}
+
+/** listeners 的 key 映射成 React 回调 prop：select -> onSelect，onSelect 原样保留 */
+function toReactListeners(listeners: Record<string, Listener> | undefined) {
+  if (!listeners) return {}
+  return Object.entries(listeners).reduce<Record<string, Listener>>((acc, [key, fn]) => {
+    const propName = /^on[A-Z]/.test(key)
+      ? key
+      : `on${key.charAt(0).toUpperCase()}${key.slice(1)}`
+    acc[propName] = fn
+    return acc
+  }, {})
+}
+
+/** 纯文本当文本节点，带标签的才走 dangerouslySetInnerHTML */
+function renderSlot(html: string | undefined) {
+  if (!html) return null
+  if (/<[a-z][\s\S]*>/i.test(html)) {
+    return <span dangerouslySetInnerHTML={{ __html: html }} />
+  }
+  return html
+}
+
+/**
+ * 通用的组件属性实验台：组件、schema 都由宿主通过 props 传入。
+ * 不 import 任何具体组件，也不认识组件包的 schema 目录。
+ *
+ * 与 Vue 版 PropsPlayground 同构：tabs 切换组件、舞台预览、右侧属性面板；
+ * presets 固定复杂 props，其余可绑定 props 交给面板读写。
+ */
+export default function PropsPlayground({
+  components,
+  schemas,
+  presets = {},
+  listeners = {},
+  stageClasses = {},
+  stageStyles = {},
+  slotHtml = {},
+}: PropsPlaygroundProps) {
+  const names = useMemo(
+    () => Object.keys(schemas).filter((name) => components[name]),
+    [schemas, components],
+  )
+  const [selected, setSelected] = useState<string>('')
+  const [values, setValues] = useState<Record<string, unknown>>({})
+  const [mountKey, setMountKey] = useState(0)
+
+  useEffect(() => {
+    if (!names.includes(selected) && names.length) {
+      select(names[0])
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [names])
+
+  const schema = schemas[selected] || []
+  const ActiveComp = components[selected]
+  const activePreset = presets[selected] || {}
+  const activeListeners = toReactListeners(listeners[selected])
+  const activeSlot = slotHtml[selected] || {}
+
+  function select(name: string) {
+    if (name === selected) return
+    setSelected(name)
+    // presets 既承载复杂 props，也可以覆盖面板初始值
+    const preset = presets[name] || {}
+    setValues({ ...createValues(schemas[name] || []), ...preset })
+  }
+
+  const remount = () => setMountKey((key) => key + 1)
+
+  if (!names.length) {
+    return (
+      <p className="props-playground__empty">
+        PropsPlayground 需要 components（组件映射）和 schemas（propsSchema 映射）两个 props
+      </p>
+    )
+  }
+
+  const activeProps = { ...activePreset, ...values }
+
+  return (
+    <div className="props-playground">
+      <div className="props-playground__bar">
+        <div className="props-playground__tabs">
+          {names.map((name) => (
+            <button
+              key={name}
+              type="button"
+              className={`props-playground__tab${name === selected ? ' is-active' : ''}`}
+              onClick={() => select(name)}
+            >
+              {name}
+            </button>
+          ))}
+        </div>
+        <button type="button" className="props-playground__action" onClick={remount}>
+          重新挂载
+        </button>
+      </div>
+
+      <div className="props-playground__body">
+        <div
+          className={`props-playground__stage${stageClasses[selected] ? ` ${stageClasses[selected]}` : ''}`}
+          style={stageStyles[selected]}
+        >
+          {ActiveComp ? (
+            <ActiveComp
+              key={`${selected}-${mountKey}`}
+              {...activeProps}
+              {...activeListeners}
+            >
+              {renderSlot(activeSlot.default)}
+            </ActiveComp>
+          ) : (
+            <p className="props-playground__empty">组件 {selected} 未导出</p>
+          )}
+        </div>
+
+        <PropsPanel
+          key={selected}
+          className="props-playground__panel"
+          compName={selected}
+          schema={schema}
+          value={values}
+          onChange={setValues}
+        />
+      </div>
+    </div>
+  )
+}

package/src/configs/subApp.ts

@@ -0,0 +1,8 @@
+/*
+|--------------------------------------------------------------------------
+|
+| 对应 package.json/appGroupName
+|
+|--------------------------------------------------------------------------
+*/
+export const LIB_NAME = 'libs-react-leva'

package/src/core/__tests__/pure.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, assert } from 'vitest'
+import { bindableProps, complexPropNames, createValues, isBindable } from '../schema'
+import type { PropSchema } from '../schema'
+import { toLevaSchema } from '../leva'
+
+const schema: PropSchema[] = [
+  { name: 'active', type: 'boolean', description: '', default: '', required: false, version: '', isEvent: false, bindable: true, value: false },
+  { name: 'scale', type: 'number', description: '', default: '', required: false, version: '', isEvent: false, bindable: true, value: 0, control: { min: 0, max: 2 } },
+  { name: 'items', type: 'Array', description: '', default: '', required: false, version: '', isEvent: false, bindable: false },
+  { name: 'onChange', type: 'function', description: '', default: '', required: false, version: '', isEvent: true, bindable: false },
+]
+
+describe('schema 纯函数', () => {
+  it('isBindable 只认 bindable 标记', () => {
+    assert.equal(isBindable(schema[0]), true)
+    assert.equal(isBindable(schema[2]), false)
+    assert.equal(isBindable(null), false)
+  })
+
+  it('createValues 只收集可绑定 prop 的初始值', () => {
+    assert.deepEqual(createValues(schema), { active: false, scale: 0 })
+    assert.deepEqual(createValues(undefined), {})
+  })
+
+  it('bindableProps / complexPropNames 分类正确', () => {
+    assert.deepEqual(
+      bindableProps(schema).map((prop) => prop.name),
+      ['active', 'scale'],
+    )
+    assert.deepEqual(complexPropNames(schema), ['items'])
+  })
+})
+
+describe('toLevaSchema', () => {
+  it('只转可绑定 prop，合并 control 配置', () => {
+    const leva = toLevaSchema(schema)
+    assert.equal(leva.active.value, false)
+    assert.equal(leva.scale.min, 0)
+    assert.equal(leva.scale.max, 2)
+    assert.ok(!('items' in leva))
+  })
+
+  it('受控值优先于 schema 初始值', () => {
+    const leva = toLevaSchema(schema, { scale: 1.5 })
+    assert.equal(leva.scale.value, 1.5)
+  })
+})

package/src/core/leva.ts

@@ -0,0 +1,40 @@
+/*
+|--------------------------------------------------------------------------
+|
+| 把与框架无关的 propsSchema 转成 Leva 的 controls schema 纯函数
+|
+| 面板组件只关心：schema 转控件配置、值从哪来；控件库本身在 PropsPanel 里挂载
+|
+|--------------------------------------------------------------------------
+*/
+import type { PropSchema } from './schema'
+import { bindableProps } from './schema'
+
+/** Leva 单个控件配置：value + label，其余 min / max / step / options 等原样透传 */
+export type LevaControl = Record<string, any>
+
+/** Leva controls schema：{ [propName]: LevaControl } */
+export type LevaSchema = Record<string, any>
+
+/**
+ * 把 propsSchema.json 内容转成 Leva 的 schema 对象。
+ *
+ * @param schema 组件的 propsSchema 数组
+ * @param values 已有的面板值（受控用法下优先取这里，缺省回落到 schema 里的初始值）
+ */
+export function toLevaSchema(
+  schema: PropSchema[] | undefined | null,
+  values?: Record<string, unknown>,
+): LevaSchema {
+  const merged = values || {}
+  return bindableProps(schema).reduce<LevaSchema>((acc, prop) => {
+    acc[prop.name] = {
+      value: Object.prototype.hasOwnProperty.call(merged, prop.name)
+        ? merged[prop.name]
+        : prop.value,
+      label: prop.description || prop.name,
+      ...(prop.control || {}),
+    }
+    return acc
+  }, {})
+}

package/src/core/schema.ts

@@ -0,0 +1,57 @@
+/*
+|--------------------------------------------------------------------------
+|
+| schema 的纯函数工具：与框架无关，形状与 @melt-js/libs-vue3-leva 保持一致
+|
+|--------------------------------------------------------------------------
+*/
+
+/** 透传给面板控件库（Leva）的额外配置：min / max / step / options ... */
+export type PropControl = Record<string, unknown>
+
+/** propsSchema.json 里单个 prop 的形状（与 Vue 版同构） */
+export interface PropSchema {
+  /** 属性名 */
+  name: string
+  /** 原始类型串，如 number / string / 'wheel' | 'fan' / Items[] */
+  type: string
+  /** JSDoc 描述 */
+  description: string
+  /** 源码里的默认值表达式（字面量或 computed 文本） */
+  default: string
+  required: boolean
+  version: string
+  /** 是否为事件回调（onXxx / function） */
+  isEvent: boolean
+  /** 是否能在面板上生成控件（boolean / number / string） */
+  bindable: boolean
+  /** 可绑定 prop 的面板初始值（已转成字面量） */
+  value?: string | number | boolean
+  /** 控件配置，原样交给 Leva */
+  control?: PropControl
+}
+
+/** 该 prop 是否能在面板上生成控件（boolean / number / string） */
+export function isBindable(prop: PropSchema | null | undefined): boolean {
+  return Boolean(prop && prop.bindable)
+}
+
+/** 按 schema 生成面板的初始值，只包含可绑定（bindable）的 prop */
+export function createValues(schema: PropSchema[] | undefined | null): Record<string, unknown> {
+  return (schema || []).reduce<Record<string, unknown>>((values, prop) => {
+    if (isBindable(prop)) values[prop.name] = prop.value
+    return values
+  }, {})
+}
+
+/** 没有生成控件的 prop 名（复杂对象 / 数组 / 事件等），面板上给个提示 */
+export function complexPropNames(schema: PropSchema[] | undefined | null): string[] {
+  return (schema || [])
+    .filter((prop) => !prop.isEvent && !isBindable(prop))
+    .map((prop) => prop.name)
+}
+
+/** 可生成控件的 prop 列表 */
+export function bindableProps(schema: PropSchema[] | undefined | null): PropSchema[] {
+  return (schema || []).filter(isBindable)
+}

package/src/entrance/libProperties.ts

@@ -0,0 +1,16 @@
+import PropsPanel from '../PropsPanel'
+import PropsPlayground from '../PropsPlayground'
+
+export { PropsPanel, PropsPlayground }
+export * from '../core/schema'
+export * from '../core/leva'
+
+/**
+ * 这个远程包自身持有面板实现（PropsPanel / PropsPlayground），并把它暴露给使用方。
+ * 默认导出对象同时挂在 hel 模块上，供 preFetchLib 后按具名取值。
+ */
+const libProperties = { PropsPanel, PropsPlayground }
+
+export type LibProperties = typeof libProperties
+
+export default libProperties

package/src/entrance/libTypes.ts

@@ -0,0 +1,16 @@
+import { exposeLib } from 'hel-lib-proxy'
+import { LIB_NAME } from '../configs/subApp'
+import type { LibProperties } from './libProperties'
+
+/**
+ * 组件类型导出文件，同时作为 rollup 打包入口：打包后是仅含 hel-lib-proxy 的空壳，
+ * 真正的组件在运行时由 hel 通过 hel_dist 载入。
+ */
+export const lib = exposeLib<LibProperties>(LIB_NAME)
+
+export const PropsPanel = lib.PropsPanel
+export const PropsPlayground = lib.PropsPlayground
+
+export type Lib = LibProperties
+
+export default lib

package/src/index.ts

@@ -0,0 +1,19 @@
+async function main() {
+  const { isMasterApp } = await import('hel-iso')
+  const { libReady } = await import('hel-lib-proxy')
+  const { LIB_NAME } = await import('./configs/subApp')
+
+  const libProperties = await import('./entrance/libProperties')
+  // !!!注意这句话不能删掉，否则使用方无法获取到模块
+  libReady(LIB_NAME, libProperties.default)
+
+  // 非子应用时自己挂载调试页，方便本地独立验证（被宿主载入时不会触发）
+  if (isMasterApp()) {
+    await import('./loadApp')
+  }
+}
+
+main().catch(console.error)
+
+// avoid isolatedModules warning
+export default 'HEL REMOTE MOD'

package/src/loadApp.tsx

@@ -0,0 +1,44 @@
+/**
+ * 仅本地调试用：直接访问本工程（dev / preview）时渲染一个玩具组件演示面板，
+ * 作为远程库被宿主加载时不会执行（见 src/index.ts 的 isMasterApp 判断）。
+ */
+import React from 'react'
+import { createRoot } from 'react-dom/client'
+import PropsPlayground from './PropsPlayground'
+
+const Toy: React.FC<Record<string, unknown>> = (props) => (
+  <div style={{ padding: 24, fontSize: `${props.size}px` }}>{props.label as string}</div>
+)
+
+const SCHEMA = [
+  {
+    name: 'label',
+    type: 'string',
+    description: '文案',
+    default: '"hello"',
+    required: false,
+    version: '',
+    isEvent: false,
+    bindable: true,
+    value: 'hello',
+  },
+  {
+    name: 'size',
+    type: 'number',
+    description: '字号',
+    default: '16',
+    required: false,
+    version: '',
+    isEvent: false,
+    bindable: true,
+    value: 16,
+    control: { min: 12, max: 48, step: 1 },
+  },
+]
+
+const node = document.getElementById('container') || document.getElementById('root')
+if (node) {
+  createRoot(node).render(
+    <PropsPlayground components={{ Toy }} schemas={{ Toy: SCHEMA }} />,
+  )
+}

package/src/shims/jsx-runtime.mjs

@@ -0,0 +1,18 @@
+/**
+ * dev 专用 shim：react/jsx-runtime 与 react/jsx-dev-runtime 映射到全局 React。
+ * 全局 React UMD 不暴露 jsx/jsxs，这里基于 React.createElement 自行包装实现。
+ */
+const React = globalThis.React
+
+const { Fragment } = React
+
+function jsx(type, props, key) {
+  const next = props ? { ...props } : {}
+  if (key != null) next.key = key
+  return React.createElement(type, next)
+}
+
+const jsxs = jsx
+const jsxDEV = jsx
+
+export { Fragment, jsx, jsxs, jsxDEV }

package/src/shims/react-dom-client.mjs

@@ -0,0 +1,8 @@
+/** dev 专用 shim：react-dom/client 映射到全局 ReactDOM（见 react.mjs 说明）。 */
+const ReactDOM = globalThis.ReactDOM
+
+export default ReactDOM
+
+const { createRoot, hydrateRoot } = ReactDOM
+
+export { createRoot, hydrateRoot }

package/src/shims/react-dom.mjs

@@ -0,0 +1,8 @@
+/** dev 专用 shim：react-dom 映射到全局 ReactDOM（见 react.mjs 说明）。 */
+const ReactDOM = globalThis.ReactDOM
+
+export default ReactDOM
+
+const { createPortal, flushSync, version } = ReactDOM
+
+export { createPortal, flushSync, version }

package/src/shims/react-is.mjs

@@ -0,0 +1,2 @@
+/** dev 专用 shim：react-is 映射到全局 ReactIs（见 react.mjs 说明）。 */
+export default globalThis.ReactIs

package/src/shims/react.mjs

@@ -0,0 +1,72 @@
+/**
+ * dev 专用 shim：把 react 解析到宿主（或本地 index.html UMD）注入的全局 React，
+ * 避免 vite dep optimizer 内联出第二份 React 实例而触发 invalid hook call。
+ * 生产 build 走 rollup external + UMD globals，不经过此文件。
+ */
+const React = globalThis.React
+
+export default React
+
+const {
+  useState,
+  useEffect,
+  useMemo,
+  useCallback,
+  useRef,
+  useContext,
+  useReducer,
+  useImperativeHandle,
+  useLayoutEffect,
+  useDebugValue,
+  useSyncExternalStore,
+  useTransition,
+  useDeferredValue,
+  useId,
+  useInsertionEffect,
+  forwardRef,
+  createElement,
+  Fragment,
+  isValidElement,
+  cloneElement,
+  Children,
+  createContext,
+  memo,
+  lazy,
+  Suspense,
+  Profiler,
+  StrictMode,
+  startTransition,
+  version,
+} = React
+
+export {
+  useState,
+  useEffect,
+  useMemo,
+  useCallback,
+  useRef,
+  useContext,
+  useReducer,
+  useImperativeHandle,
+  useLayoutEffect,
+  useDebugValue,
+  useSyncExternalStore,
+  useTransition,
+  useDeferredValue,
+  useId,
+  useInsertionEffect,
+  forwardRef,
+  createElement,
+  Fragment,
+  isValidElement,
+  cloneElement,
+  Children,
+  createContext,
+  memo,
+  lazy,
+  Suspense,
+  Profiler,
+  StrictMode,
+  startTransition,
+  version,
+}