@composy/solution-vue

@composy/solution-vue

LDesign Solution 的 Vue 3 应用启动器。它把 @composy/solution-core 的运行时（SolutionRuntime）接入 Vue 3 应用：负责创建应用、通过 provide/inject 注入 solution 运行时、按需挂载到 DOM，并提供 useSolution 组合式函数用来管理挂载容器与实例生命周期。SolutionComponent 直接桥接 core 的 <ldesign-solution-shell>，并自动加载 core 的 Less 编译样式，不在 Vue 层重复实现 UI 或样式。

• 基于 Vue ^3.5.0（peer dependency），TypeScript 编写。
• 依赖 @composy/solution-core（运行时核心，框架无关）。
• 使用 @composy/builder 和 Rolldown，配置位于 .ldesign/builder.config.ts；提供 dist、es、esm、lib 四套产物，构建后会校验这些目录与 package.json 导出字段。

安装

pnpm add @composy/solution-vue
# 或
npm install @composy/solution-vue
# 或
yarn add @composy/solution-vue

vue 作为 peer dependency 需自行安装；@composy/solution-core 会自动作为依赖装入。

目录结构

packages/solution/packages/vue/
├── src/
│   ├── index.ts                 # 公共入口：createVueSolutionApp + 全量导出
│   ├── runtime.ts               # SOLUTION_RUNTIME_KEY / useSolutionRuntime
│   ├── components/
│   │   ├── Solution.vue         # Solution 组件（SolutionComponentInstance 类型）
│   │   └── index.ts
│   └── composables/
│       ├── useSolution.ts       # useSolution 组合式函数
│       └── index.ts
├── package.json
├── tsconfig.json
└── README.md                    # 本文档

构建产物目录：es/（ESM）、lib/（CJS）、esm/、dist/（browser bundle + dist/style.css）。

核心 API

createVueSolutionApp(options): Promise<VueSolutionApp>

创建并返回一个已接入 solution 运行时的 Vue 3 应用。这是一个 async 函数。

async function createVueSolutionApp(options: CreateVueSolutionAppOptions): Promise<VueSolutionApp>

CreateVueSolutionAppOptions

VueSolutionApp

行为说明：

• 通过 provide(SOLUTION_RUNTIME_KEY, runtime) 与 provide('ldesign:solution', runtime) 注入运行时，供任意后代用 useSolutionRuntime() 读取。
• 传入自定义 runtime 时，本启动器 不 负责销毁它（ownsRuntime = false）。

useSolution<T>(options?): UseSolutionReturn<T>

管理一个挂载容器与业务实例的生命周期的组合式函数。

function useSolution<T = unknown>(options: UseSolutionOptions<T> = {}): UseSolutionReturn<T>

UseSolutionOptions<T>

UseSolutionReturn<T>

onMounted 时发出 solution:ready 事件，onUnmounted 时发出 solution:cleanup 事件。

useSolutionRuntime(): SolutionRuntime

在组件 setup 中读取注入的 solution 运行时；若不在 solution 应用内调用会抛错。

SOLUTION_RUNTIME_KEY

类型为 InjectionKey<SolutionRuntime> 的注入 key。

其它导出类型

• SolutionOptions、SolutionRuntime、SolutionProduct（来自 @composy/solution-core，从这里 type-only 复导出）
• UseSolutionOptions、UseSolutionReturn
• SolutionComponentInstance（来自 components/Solution.vue）

使用示例（Vue 3 + TypeScript）

入口：

// src/main.ts
import { createVueSolutionApp } from '@composy/solution-vue'
import Root from './Root.vue'

async function bootstrap() {
  const { app, runtime, unmount } = await createVueSolutionApp({
    rootComponent: Root,
    selector: '#app',
    product: {
      id: 'my-product',
      version: '1.0.0',
    },
    debug: import.meta.env.DEV,
  })

  // app 已挂载；需要卸载时：
  // unmount()
}

bootstrap()

组件内使用运行时 + 组合式函数：

<script setup lang="ts">
import { useSolution, useSolutionRuntime } from '@composy/solution-vue'

const runtime = useSolutionRuntime()

interface Player {
  play: () => void
  stop: () => void
}

const { containerRef, isReady, instance } = useSolution<Player>({
  create: (_container, rt) => {
    console.log('runtime name:', rt.name)
    return { play() {}, stop() {} }
  },
  destroy: (player) => player.stop(),
})
</script>

<template>
  <div ref="containerRef">
    <span v-if="isReady">solution instance ready</span>
  </div>
</template>

构建脚本 & 验证命令

推荐的最小验证链路：

pnpm type-check && pnpm lint:check && pnpm test && pnpm build

产物说明

• es/ — ESM 模块产物（index.js + .d.ts），"module" / "import" 入口，也是类型入口。
• lib/ — CJS 产物（index.cjs），"main" / "require" 入口。
• esm/ — 额外 ESM 产物目录（含 style/**）。
• dist/ — browser bundle（index.js，"browser" 入口）与样式 style.css（"style" 字段）。
• 子入口：@composy/solution-vue/components、@composy/solution-vue/components/*、@composy/solution-vue/composables、@composy/solution-vue/composables/*，各自带 ESM/CJS 与类型映射。

// package.json exports 摘要
{
  ".": { "types": "./es/index.d.ts", "import": "./es/index.js", "require": "./lib/index.cjs" },
  "./components": {
    "types": "./es/components/index.d.ts",
    "import": "./es/components/index.js",
    "require": "./lib/components/index.cjs",
  },
  "./components/*": {
    "types": "./es/components/*.d.ts",
    "import": "./es/components/*.js",
    "require": "./lib/components/*.cjs",
  },
  "./composables": {
    "types": "./es/composables/index.d.ts",
    "import": "./es/composables/index.js",
    "require": "./lib/composables/index.cjs",
  },
  "./composables/*": {
    "types": "./es/composables/*.d.ts",
    "import": "./es/composables/*.js",
    "require": "./lib/composables/*.cjs",
  },
}

备注

• 启动器是 async 的： createVueSolutionApp 返回 Promise<VueSolutionApp>，请使用 await 或 .then() 消费。
• 运行时所有权： 传入自定义 runtime 时不受启动器管理；只有自建运行时才会在 unmount() 时被 destroy()。
• 单例上下文： useSolutionRuntime() 依赖 inject，必须在 solution 应用（createVueSolutionApp 创建）的组件 setup 内调用，否则抛错。
• 框架边界： 本包只负责“Vue 应用 + solution 运行时”的接线与生命周期，产品、协议、状态、纯逻辑等放在 @composy/solution-core，不要在 Vue 适配层重复实现。
• Side effects 说明： *.vue、*.tsx、*.jsx、dist/*、es/**/style/**、esm/**/style/** 被标记为 sideEffects，样式与 Vue 组件不会被 tree-shaking 误删。