0
# Vue Framework Adapter
1

2
The Vue Framework Adapter provides a unified API abstraction that works identically across Vue 2, Vue 2.7, and Vue 3. It handles version-specific differences in composition API, lifecycle hooks, component rendering, and provides cross-framework compatibility for the entire TinyVue ecosystem.
3

4
## Capabilities
5

6
### Composition API Hooks
7

8
Provides a unified interface to Vue's composition API that works across all Vue versions.
9

10
```typescript { .api }
11
/**
12
 * Unified composition API hooks that work across Vue 2 and Vue 3
13
 */
14
interface AdapterHooks {
15
  /** Create a reactive reference */
16
  ref<T>(value: T): Ref<T>;
17
  /** Create a computed property */
18
  computed<T>(getter: () => T): ComputedRef<T>;
19
  /** Watch for changes in reactive data */
20
  watch<T>(source: T, callback: (newVal: T, oldVal: T) => void): void;
21
  /** Lifecycle hook - component mounted */
22
  onMounted(callback: () => void): void;
23
  /** Lifecycle hook - before component unmounts */
24
  onBeforeUnmount(callback: () => void): void;
25
  /** Get current component instance */
26
  getCurrentInstance(): any;
27
  /** Provide value to child components */
28
  provide<T>(key: string | symbol, value: T): void;
29
  /** Inject value from parent components */
30
  inject<T>(key: string | symbol, defaultValue?: T): T;
31
}
32

33
const hooks: AdapterHooks;
34
```
35

36
### Additional Adapter Utilities
37

38
Extended utilities for routing, event handling, directive processing, and component management.
39

40
```typescript { .api }
41
/**
42
 * Access Vue Router instance and current route
43
 */
44
function useRouter(instance?: any): {
45
  route: any;
46
  router: any;
47
};
48

49
/**
50
 * Create an event emitter instance
51
 */
52
function emitter(): any;
53

54
/**
55
 * Process Vue directives for cross-framework compatibility
56
 */
57
function directive(directives: any): any;
58

59
/**
60
 * Create a component instance with design configuration
61
 */
62
function createComponent(config: {
63
  component: any;
64
  propsData?: any;
65
  el: any;
66
}): any;
67

68
/**
69
 * Get element status class from class definitions
70
 */
71
function getElementStatusClass(classes: Record<string, string>, key: string): string;
72

73
/**
74
 * Vue 3 Teleport component (null in Vue 2)
75
 */
76
const Teleport: any;
77

78
/**
79
 * Vue KeepAlive component
80
 */
81
const KeepAlive: any;
82
```
83

84
**Usage Examples:**
85

86
```typescript
87
import { hooks } from "@opentiny/vue-common";
88

89
// Create reactive state
90
const count = hooks.ref(0);
91
const doubled = hooks.computed(() => count.value * 2);
92

93
// Watch for changes
94
hooks.watch(count, (newVal, oldVal) => {
95
  console.log(`Count changed from ${oldVal} to ${newVal}`);
96
});
97

98
// Use lifecycle hooks
99
hooks.onMounted(() => {
100
  console.log('Component mounted');
101
});
102

103
hooks.onBeforeUnmount(() => {
104
  console.log('Component unmounting');
105
});
106
```
107

108
### Framework Detection
109

110
Boolean flags for detecting the current Vue framework version.
111

112
```typescript { .api }
113
/** True when running in Vue 2 environment */
114
const isVue2: boolean;
115

116
/** True when running in Vue 3 environment */
117
const isVue3: boolean;
118
```
119

120
### Component Definition
121

122
Cross-framework component definition that works with both Vue 2 and Vue 3.
123

124
```typescript { .api }
125
/**
126
 * Define a component that works across Vue versions
127
 * @param options - Component options object
128
 * @returns Component constructor
129
 */
130
function defineComponent<T>(options: T): DefineComponent;
131

132
/**
133
 * Define an async component with lazy loading
134
 * @param loader - Function that returns a Promise resolving to component
135
 * @returns Async component constructor
136
 */
137
function defineAsyncComponent(loader: () => Promise<any>): DefineComponent;
138
```
139

140
### Render Functions
141

142
Unified render function and virtual node utilities.
143

144
```typescript { .api }
145
/**
146
 * Hyperscript render function (h function)
147
 * @param tag - Element tag or component
148
 * @param props - Element props/attributes  
149
 * @param children - Child elements or text
150
 * @returns Virtual node
151
 */
152
function h(tag: any, props?: any, children?: any): any;
153

154
/**
155
 * Mark object as non-reactive (Vue 3) or pass-through (Vue 2)
156
 * @param obj - Object to mark as raw
157
 * @returns Raw object
158
 */
159
function markRaw<T>(obj: T): T;
160

161
/**
162
 * Parse and normalize virtual nodes across Vue versions
163
 * @param vnode - Virtual node to parse
164
 * @returns Normalized vnode
165
 */
166
function parseVnode(vnode: any): any;
167

168
/**
169
 * Check if a virtual node is empty
170
 * @param vnode - Virtual node to check
171
 * @returns True if vnode is empty
172
 */
173
function isEmptyVnode(vnode: any): boolean;
174

175
/**
176
 * Type guard for virtual nodes
177
 * @param vnode - Value to check
178
 * @returns True if value is a vnode
179
 */
180
function isVnode(vnode: any): boolean;
181
```
182

183
### Built-in Components
184

185
Cross-framework compatible built-in components.
186

187
```typescript { .api }
188
/**
189
 * Teleport/Portal component for rendering content in different DOM location
190
 * Vue 3: Uses native Teleport
191
 * Vue 2: Uses custom implementation
192
 */
193
const Teleport: DefineComponent;
194

195
/**
196
 * KeepAlive component for caching component instances
197
 */
198
const KeepAlive: DefineComponent;
199
```
200

201
### Directive Support
202

203
Directive lifecycle hook normalization across Vue versions.
204

205
```typescript { .api }
206
/**
207
 * Normalize directive lifecycle hooks across Vue versions
208
 * @param directives - Directive definition object
209
 * @returns Normalized directives
210
 */
211
function directive(directives: any): any;
212
```
213

214
### Component Creation and Rendering
215

216
Utilities for creating and rendering components with design system integration.
217

218
```typescript { .api }
219
/**
220
 * Create component with design system integration
221
 * @param design - Design system configuration
222
 * @returns Component creation function
223
 */
224
function createComponentFn(design: any): (config: any) => DefineComponent;
225

226
/**
227
 * Unified component rendering function
228
 * @param config - Render configuration
229
 * @returns Rendered component
230
 */
231
function renderComponent(config: {
232
  view?: any;
233
  component?: any;
234
  props: any;
235
  context: any;
236
  extend?: any;
237
  customDesignProps?: any;
238
}): any;
239
```
240

241
### Application Context
242

243
Access to application-level context and properties.
244

245
```typescript { .api }
246
/**
247
 * Get application context
248
 * @returns Vue application context
249
 */
250
function appContext(): any;
251

252
/**
253
 * Get global application properties
254
 * @returns Global properties object
255
 */
256
function appProperties(): any;
257

258
/**
259
 * Get root configuration from context
260
 * @param context - Component context
261
 * @returns Root configuration object
262
 */
263
function rootConfig(context?: any): any;
264
```
265

266
### Event System
267

268
Event emitter creation and management utilities.
269

270
```typescript { .api }
271
/**
272
 * Create an event emitter instance
273
 * @returns Event emitter with emit, on, once, off methods
274
 */
275
function emitter(): {
276
  emit(event: string, ...args: any[]): void;
277
  on(event: string, callback: (...args: any[]) => void): void;
278
  once(event: string, callback: (...args: any[]) => void): void;
279
  off(event: string, callback?: (...args: any[]) => void): void;
280
};
281
```
282

283
### Router Integration
284

285
Router integration utilities for navigation support.
286

287
```typescript { .api }
288
/**
289
 * Get router instance and current route
290
 * @param instance - Component instance (optional)
291
 * @returns Object with route and router
292
 */
293
function useRouter(instance?: any): {
294
  route: any;
295
  router: any;
296
};
297
```
298

299
### Utility Functions
300

301
Additional utility functions for component development.
302

303
```typescript { .api }
304
/**
305
 * Get current or parent component name
306
 * @returns Component name string
307
 */
308
function getComponentName(): string;
309

310
/**
311
 * Get custom component properties
312
 * @returns Custom properties object
313
 */
314
function getCustomProps(): any;
315

316
/**
317
 * Filter and combine props and attributes
318
 * @param props - Component props
319
 * @param attrs - Component attributes  
320
 * @returns Filtered props object
321
 */
322
function bindFilter(props: any, attrs: any): any;
323

324
/**
325
 * Get CSS classes based on key patterns
326
 * @param classes - Classes object
327
 * @param key - Key to lookup
328
 * @returns CSS class string
329
 */
330
function getElementCssClass(classes: any, key: string): string;
331

332
/**
333
 * Generate status-specific class names
334
 * @param className - Base class name
335
 * @param status - Status identifier
336
 * @returns Status-specific class name
337
 */
338
function getElementStatusClass(className: string, status: string): string;
339
```
340

341
### Framework Tools
342

343
Comprehensive toolkit providing framework-specific utilities and component communication.
344

345
```typescript { .api }
346
/**
347
 * Get comprehensive framework toolkit
348
 * @param context - Component context
349
 * @param mode - Component mode (pc/mobile/mobile-first)
350
 * @returns Tools object with utilities
351
 */
352
function tools(context: any, mode: string): {
353
  framework: 'vue2' | 'vue2.7' | 'vue3';
354
  isPCMode: boolean;
355
  isMobileMode: boolean;
356
  vm: any;
357
  emit: (...args: any[]) => void;
358
  emitter: any;
359
  refs: any;
360
  slots: any;
361
  scopedSlots: any;
362
  attrs: any;
363
  parent: any;
364
  route: any;
365
  router: any;
366
  dispatch: (componentName: string, eventName: string, params?: any) => void;
367
  broadcast: (componentName: string, eventName: string, params?: any) => void;
368
  parentHandler: (condition: any) => any;
369
  childrenHandler: (condition: any) => any;
370
  i18n: any;
371
  nextTick: (callback: () => void) => void;
372
  constants: any;
373
  mode: string;
374
  service: any;
375
  getService: () => any;
376
  setParentAttribute: (config: { name: string; value: any }) => void;
377
  defineInstanceProperties: (props: any) => void;
378
  defineParentInstanceProperties: (props: any) => void;
379
};
380
```
381

382
## Virtual Import System
383

384
The adapter uses a virtual import system that resolves to version-specific implementations:
385

386
- **Virtual Import**: `'virtual:common/adapter/vue'`
387
- **Vue 2 Resolution**: `packages/vue-common/src/adapter/vue2/index.ts`
388
- **Vue 2.7 Resolution**: `packages/vue-common/src/adapter/vue2.7/index.ts`  
389
- **Vue 3 Resolution**: `packages/vue-common/src/adapter/vue3/index.ts`
390

391
This system allows the same import statement to work across all Vue versions while providing the appropriate implementation for each framework version.