{"_id":"@baihuiru/trans-components","name":"@baihuiru/trans-components","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@baihuiru/trans-components","version":"1.0.0","description":"Transform React and Vue components to Web Components for cross-framework sharing","type":"module","main":"dist/index.js","module":"dist/index.esm.js","types":"dist/index.d.ts","scripts":{"build":"rollup -c","dev":"rollup -c -w","type-check":"tsc --noEmit","test":"jest","lint":"eslint src --ext .ts,.tsx,.js,.jsx","format":"prettier --write src/**/*.{ts,tsx,js,jsx}","clean":"rimraf dist","prepublishOnly":"npm run clean && npm run build","demo":"vite serve examples --port 3001"},"keywords":["web-components","react","vue","cross-framework","component-library","transform","lit"],"author":{"name":"huirubai"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/baihuiru/trans.git"},"dependencies":{"@lit-labs/react":"^1.0.0","lit":"^3.0.0","tslib":"^2.8.1"},"peerDependencies":{"react":">=16.8.0","react-dom":">=16.8.0","vue":">=3.0.0"},"devDependencies":{"@rollup/plugin-commonjs":"^25.0.0","@rollup/plugin-node-resolve":"^15.0.0","@rollup/plugin-terser":"^0.4.0","@rollup/plugin-typescript":"^11.0.0","@types/jest":"^29.0.0","@types/node":"^20.0.0","@types/react":"^18.0.0","@types/react-dom":"^18.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.0.0","jest":"^29.0.0","jest-environment-jsdom":"^30.1.1","prettier":"^3.0.0","rimraf":"^5.0.0","rollup":"^4.0.0","ts-jest":"^29.0.0","typescript":"^5.0.0","vite":"^5.0.0"},"_id":"@baihuiru/trans-components@1.0.0","gitHead":"2cd03b998d912e3f696fe1bfbadc5aa74a373b2e","bugs":{"url":"https://github.com/baihuiru/trans/issues"},"homepage":"https://github.com/baihuiru/trans#readme","_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-rPwj0Th7NFZyZd3liPkSc2kKfvVb+zWn55NH5LfWLleZjmiM2ij9evQRoOBc4nl/9bPKTajh5u1jxS/7cbohIA==","shasum":"8438eb8da437015eae2c23d5ae3fc67eca7c4124","tarball":"https://registry.npmjs.org/@baihuiru/trans-components/-/trans-components-1.0.0.tgz","fileCount":24,"unpackedSize":217133,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHI9nMBi8GjgMbZJj4ANiN4/QsQUMvL8Sn4hNFlzvBgoAiBU3id6J8qiQqC8fwRqv8+wvJcde4o6ell2oF76/pz9CA=="}]},"_npmUser":{"name":"baihuiru","email":"bhremail@163.com"},"directories":{},"maintainers":[{"name":"baihuiru","email":"bhremail@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/trans-components_1.0.0_1756378037292_0.1577553437121184"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-28T10:47:17.182Z","1.0.0":"2025-08-28T10:47:17.500Z","modified":"2025-08-28T10:47:17.695Z"},"maintainers":[{"name":"baihuiru","email":"bhremail@163.com"}],"description":"Transform React and Vue components to Web Components for cross-framework sharing","homepage":"https://github.com/baihuiru/trans#readme","keywords":["web-components","react","vue","cross-framework","component-library","transform","lit"],"repository":{"type":"git","url":"git+https://github.com/baihuiru/trans.git"},"author":{"name":"huirubai"},"bugs":{"url":"https://github.com/baihuiru/trans/issues"},"license":"MIT","readme":"# @trans/components\n\n一个强大的组件转换库，支持将 React 和 Vue 组件转换为 Web Components，实现真正的跨框架组件共享。\n\n## ✨ 特性\n\n- 🚀 **跨框架支持**: 支持 React 和 Vue 组件转换\n- 🎯 **零配置**: 开箱即用，简单易用\n- 🔧 **TypeScript 支持**: 完整的类型定义\n- 🎨 **样式隔离**: 支持 Shadow DOM 样式隔离\n- 📦 **体积小巧**: 基于 Lit 构建，体积轻量\n- 🔄 **双向通信**: 支持 props 传递和事件监听\n- 🛠 **插件化架构**: 支持自定义转换器\n\n## 📦 安装\n\n```bash\nnpm install @trans/components\n```\n\n### Peer Dependencies\n\n```bash\n# 如果使用 React 组件转换\nnpm install react react-dom\n\n# 如果使用 Vue 组件转换  \nnpm install vue\n```\n\n## 🚀 快速开始\n\n### React 组件转换\n\n```typescript\nimport React from 'react';\nimport { transformAndRegisterReactComponent } from '@trans/components';\n\n// 你的 React 组件\nconst MyButton = ({ text, onClick }) => (\n  <button onClick={onClick}>{text}</button>\n);\n\n// 转换配置\nconst config = {\n  tagName: 'my-button',\n  props: {\n    text: 'Click me'\n  },\n  events: ['click']\n};\n\n// 转换并注册为 Web Component\ntransformAndRegisterReactComponent(MyButton, config);\n```\n\n### Vue 组件转换\n\n```typescript\nimport { defineComponent } from 'vue';\nimport { transformAndRegisterVueComponent } from '@trans/components';\n\n// 你的 Vue 组件\nconst MyCounter = defineComponent({\n  props: ['initialValue'],\n  data() {\n    return { count: this.initialValue || 0 };\n  },\n  template: '<div>{{ count }}</div>'\n});\n\n// 转换配置\nconst config = {\n  tagName: 'my-counter',\n  props: {\n    initialValue: 0\n  },\n  events: ['change']\n};\n\n// 转换并注册为 Web Component\ntransformAndRegisterVueComponent(MyCounter, config);\n```\n\n### 在 HTML 中使用\n\n```html\n<!DOCTYPE html>\n<html>\n<head>\n  <script type=\"module\" src=\"your-components.js\"></script>\n</head>\n<body>\n  <!-- 使用转换后的 Web Components -->\n  <my-button text=\"Hello World\"></my-button>\n  <my-counter initial-value=\"10\"></my-counter>\n  \n  <script>\n    // 监听事件\n    document.querySelector('my-button').addEventListener('click', () => {\n      console.log('Button clicked!');\n    });\n    \n    document.querySelector('my-counter').addEventListener('change', (e) => {\n      console.log('Counter changed:', e.detail);\n    });\n  </script>\n</body>\n</html>\n```\n\n## 📚 API 文档\n\n### 统一 API\n\n#### `transformComponent(component, config, framework)`\n\n转换组件为 Web Component 类。\n\n```typescript\nimport { transformComponent } from '@trans/components';\n\nconst WebComponent = transformComponent(MyComponent, config, 'react');\ncustomElements.define('my-component', WebComponent);\n```\n\n#### `transformAndRegister(component, config, framework)`\n\n转换组件并自动注册为 Web Component。\n\n```typescript\nimport { transformAndRegister } from '@trans/components';\n\ntransformAndRegister(MyComponent, config, 'react');\n```\n\n#### `autoRegister(components)`\n\n批量转换和注册多个组件。\n\n```typescript\nimport { autoRegister } from '@trans/components';\n\nautoRegister([\n  { component: ReactButton, config: buttonConfig, framework: 'react' },\n  { component: VueCounter, config: counterConfig, framework: 'vue' }\n]);\n```\n\n### React 专用 API\n\n```typescript\nimport { \n  transformReactComponent,\n  transformAndRegisterReactComponent \n} from '@trans/components';\n\n// 仅转换\nconst WebComponent = transformReactComponent(MyComponent, config);\n\n// 转换并注册\ntransformAndRegisterReactComponent(MyComponent, config);\n```\n\n### Vue 专用 API\n\n```typescript\nimport { \n  transformVueComponent,\n  transformAndRegisterVueComponent \n} from '@trans/components';\n\n// 仅转换\nconst WebComponent = transformVueComponent(MyComponent, config);\n\n// 转换并注册\ntransformAndRegisterVueComponent(MyComponent, config);\n```\n\n## ⚙️ 配置选项\n\n### ComponentConfig\n\n```typescript\ninterface ComponentConfig {\n  tagName: string;           // Web Component 标签名 (必须包含连字符)\n  props?: Record<string, any>;    // 默认属性值\n  events?: string[];              // 支持的事件列表\n  styles?: string;               // CSS 样式\n  shadow?: boolean;              // 是否使用 Shadow DOM (默认: true)\n  attributes?: Record<string, string>; // HTML 属性映射\n}\n```\n\n### 完整示例\n\n```typescript\nconst config = {\n  tagName: 'my-component',\n  props: {\n    title: 'Default Title',\n    count: 0,\n    disabled: false\n  },\n  events: ['click', 'change', 'custom-event'],\n  styles: `\n    :host {\n      display: block;\n      padding: 16px;\n    }\n    \n    .container {\n      border: 1px solid #ccc;\n      border-radius: 4px;\n    }\n  `,\n  shadow: true,\n  attributes: {\n    'aria-label': 'My Component'\n  }\n};\n```\n\n## 🎯 在不同框架中使用\n\n### 在 React 中使用\n\n```tsx\nfunction App() {\n  const handleClick = () => {\n    console.log('Clicked!');\n  };\n\n  return (\n    <div>\n      <my-button text=\"React App\" onCustomEvent={handleClick} />\n    </div>\n  );\n}\n```\n\n### 在 Vue 中使用\n\n```vue\n<template>\n  <div>\n    <my-button text=\"Vue App\" @custom-event=\"handleClick\" />\n  </div>\n</template>\n\n<script>\nexport default {\n  methods: {\n    handleClick() {\n      console.log('Clicked!');\n    }\n  }\n}\n</script>\n```\n\n### 在 Angular 中使用\n\n```typescript\n// app.module.ts\nimport { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';\n\n@NgModule({\n  schemas: [CUSTOM_ELEMENTS_SCHEMA]\n})\nexport class AppModule {}\n```\n\n```html\n<!-- app.component.html -->\n<my-button text=\"Angular App\" (customEvent)=\"handleClick()\"></my-button>\n```\n\n## 🔧 高级用法\n\n### 自定义转换器\n\n```typescript\nimport { BaseTransformer, ComponentConfig } from '@trans/components';\n\nclass CustomTransformer extends BaseTransformer {\n  name = 'custom-transformer';\n  framework = 'custom' as const;\n  \n  transform(component: any, config: ComponentConfig) {\n    // 自定义转换逻辑\n    return this.createWebComponent(component, config, (element) => {\n      // 自定义渲染逻辑\n    });\n  }\n}\n\n// 注册自定义转换器\nimport { getRegistry } from '@trans/components';\nconst registry = getRegistry();\nregistry.register(new CustomTransformer());\n```\n\n### 动态属性更新\n\n```javascript\nconst component = document.querySelector('my-component');\n\n// 更新属性\ncomponent.title = 'New Title';\ncomponent.count = 10;\n\n// 监听属性变化\nconst observer = new MutationObserver((mutations) => {\n  mutations.forEach((mutation) => {\n    if (mutation.type === 'attributes') {\n      console.log('Attribute changed:', mutation.attributeName);\n    }\n  });\n});\n\nobserver.observe(component, { attributes: true });\n```\n\n## 📋 最佳实践\n\n### 1. 命名规范\n\n- Web Component 标签名必须包含连字符\n- 建议使用命名空间前缀，如 `my-app-button`\n- 事件名使用 kebab-case，如 `custom-event`\n\n### 2. 样式管理\n\n```typescript\nconst config = {\n  tagName: 'my-component',\n  styles: `\n    /* 使用 :host 选择器设置组件容器样式 */\n    :host {\n      display: block;\n      --primary-color: #1890ff;\n    }\n    \n    /* 使用 CSS 变量实现主题定制 */\n    .button {\n      background: var(--primary-color);\n    }\n    \n    /* 响应式设计 */\n    @media (max-width: 768px) {\n      :host {\n        padding: 8px;\n      }\n    }\n  `\n};\n```\n\n### 3. 事件处理\n\n```typescript\n// 组件内部触发事件\nconst handleClick = () => {\n  // 触发自定义事件\n  element.dispatchEvent(new CustomEvent('custom-click', {\n    detail: { value: 'some data' },\n    bubbles: true,\n    composed: true  // 允许事件穿越 Shadow DOM 边界\n  }));\n};\n```\n\n### 4. 性能优化\n\n- 使用 `shadow: false` 如果不需要样式隔离\n- 避免在 props 中传递大对象\n- 合理使用事件冒泡\n\n## 🔍 故障排除\n\n### 常见问题\n\n1. **组件不显示**\n   - 检查是否正确导入和注册\n   - 确认标签名包含连字符\n   - 检查浏览器控制台错误\n\n2. **样式不生效**\n   - 确认使用了正确的 CSS 选择器\n   - 检查 Shadow DOM 设置\n   - 使用 `:host` 选择器\n\n3. **事件不触发**\n   - 确认事件名在 config.events 中\n   - 检查事件监听器绑定\n   - 确认使用了 `composed: true`\n\n4. **TypeScript 类型错误**\n   - 确保安装了对应的 @types 包\n   - 检查 tsconfig.json 配置\n\n## 🤝 贡献指南\n\n欢迎贡献代码！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细信息。\n\n## 📄 许可证\n\nMIT License - 详见 [LICENSE](LICENSE) 文件。\n\n## 🙏 致谢\n\n- [Lit](https://lit.dev/) - 高性能 Web Components 库\n- [React](https://reactjs.org/) - 用户界面构建库\n- [Vue](https://vuejs.org/) - 渐进式 JavaScript 框架\n","readmeFilename":"README.md","_rev":"1-367b926af5314e9c9b2be5ee9e68dde7"}