0
# @opentiny/vue-common
1

2
@opentiny/vue-common provides foundational cross-framework compatibility utilities and adapters for building Vue components that work seamlessly across Vue 2, Vue 2.7, and Vue 3. It offers a comprehensive adapter system, theme management, responsive breakpoint detection, CSS class utilities, component setup helpers, and virtual node manipulation utilities for the TinyVue ecosystem.
3

4
## Package Information
5

6
- **Package Name**: @opentiny/vue-common
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @opentiny/vue-common`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  setup, 
16
  $setup, 
17
  hooks, 
18
  h,
19
  defineComponent,
20
  defineAsyncComponent,
21
  useBreakpoint,
22
  useInstanceSlots,
23
  useRelation,
24
  useDefer,
25
  mergeClass,
26
  stringifyCssClass,
27
  stringifyCssClassObject,
28
  stringifyCssClassArray,
29
  deduplicateCssClass,
30
  resolveMode,
31
  resolveTheme,
32
  filterAttrs,
33
  version,
34
  createComponent,
35
  directive,
36
  parseVnode,
37
  isEmptyVnode,
38
  isVnode,
39
  useRouter,
40
  emitter,
41
  Teleport,
42
  KeepAlive,
43
  getElementStatusClass,
44
  initComponent,
45
  setupComponent,
46
  $install
47
} from "@opentiny/vue-common";
48
```
49

50
Default import (includes consolidated utilities):
51

52
```typescript
53
import vueCommon from "@opentiny/vue-common";
54
// Contains h, directive, parseVnode, isEmptyVnode, useRouter, emitter, createComponent, 
55
// defineAsyncComponent, filterAttrs, initComponent, setupComponent, svg, $prefix, $props, 
56
// props, $setup, setup, hooks, getElementStatusClass, $install, isVnode
57
```
58

59
For CommonJS:
60

61
```javascript
62
const { 
63
  setup, 
64
  $setup, 
65
  hooks,
66
  h,
67
  defineComponent,
68
  useBreakpoint,
69
  useInstanceSlots,
70
  useRelation,
71
  useDefer,
72
  mergeClass,
73
  stringifyCssClass,
74
  filterAttrs,
75
  version,
76
  createComponent,
77
  directive,
78
  parseVnode,
79
  isEmptyVnode,
80
  isVnode,
81
  useRouter,
82
  emitter,
83
  Teleport,
84
  KeepAlive,
85
  getElementStatusClass,
86
  initComponent,
87
  setupComponent,
88
  $install
89
} = require("@opentiny/vue-common");
90
```
91

92
## Basic Usage
93

94
```typescript
95
import { setup, hooks, useBreakpoint, mergeClass } from "@opentiny/vue-common";
96

97
// Basic component setup with renderless pattern
98
export default {
99
  setup(props, context) {
100
    return setup({
101
      props,
102
      context,
103
      renderless: myRenderless,
104
      api: ['handleClick', 'state'],
105
      classes: {
106
        wrapper: 'tiny-component'
107
      }
108
    });
109
  }
110
};
111

112
// Use responsive breakpoints
113
const breakpoint = useBreakpoint();
114
hooks.watch(breakpoint.current, (current) => {
115
  console.log('Current breakpoint:', current); // 'sm', 'md', 'lg', 'xl', '2xl', 'default'
116
});
117

118
// Merge CSS classes with Tailwind
119
const className = mergeClass('btn', 'text-blue-500', { 'active': isActive });
120
```
121

122
## Architecture
123

124
@opentiny/vue-common is built around several key architectural components:
125

126
- **Adapter System**: Unified API abstraction across Vue 2, Vue 2.7, and Vue 3 versions
127
- **Component Setup**: Standardized setup patterns for both template-based and renderless components
128
- **Theme Resolution**: Dynamic theme switching between 'tiny' and 'saas' themes
129
- **Mode Resolution**: Responsive mode detection (pc/mobile/mobile-first)
130
- **Design System Integration**: Global design configuration and component customization
131
- **CSS Class Management**: Tailwind CSS class merging and manipulation utilities
132

133
## Capabilities
134

135
### Core Composition Hooks
136

137
Essential Vue composition hooks for component relationships, slot management, and performance optimization.
138

139
```typescript { .api }
140
function useInstanceSlots(hooks: AdapterHooks): any;
141
function useRelation(hooks: AdapterHooks): any;
142
function useDefer(maxCount?: number): {
143
  defer(n: number): boolean;
144
  reset(): void;
145
  cancel(): void;
146
};
147
```
148

149
[Core Composition Hooks](./composition-hooks.md)
150

151
### Vue Framework Utilities
152

153
Core Vue framework utilities for component definition, rendering, virtual node manipulation, routing, and event handling.
154

155
```typescript { .api }
156
function h(tag: any, props?: any, children?: any): any;
157
function defineComponent<T>(options: T): DefineComponent;
158
function defineAsyncComponent(loader: () => Promise<any>): DefineComponent;
159
function parseVnode(vnode: any): any;
160
function isEmptyVnode(vnode: any): boolean;
161
function isVnode(vnode: any): boolean;
162
function useRouter(instance?: any): { route: any; router: any };
163
function emitter(): any;
164
function directive(directives: any): any;
165
function createComponent(config: { component: any; propsData?: any; el: any }): any;
166
function getElementStatusClass(classes: Record<string, string>, key: string): string;
167
const Teleport: any;
168
const KeepAlive: any;
169
```
170

171
### Package Information
172

173
```typescript { .api }
174
const version: string;
175
```
176

177
### Component Utilities
178

179
Utility functions for component attribute management, installation, and initialization.
180

181
```typescript { .api }
182
function filterAttrs(
183
  attrs: Record<string, any>, 
184
  filters: string[], 
185
  include?: boolean
186
): Record<string, any>;
187
function initComponent(): void;
188
function $install(component: any): void;
189
let setupComponent: Record<string, any>;
190
```
191

192
### Vue Framework Adapter
193

194
Cross-framework compatibility layer providing unified APIs that work identically across Vue 2 and Vue 3. Handles version-specific differences in composition API, lifecycle hooks, and component rendering.
195

196
```typescript { .api }
197
interface AdapterHooks {
198
  ref<T>(value: T): Ref<T>;
199
  computed<T>(getter: () => T): ComputedRef<T>;
200
  watch<T>(source: T, callback: (newVal: T, oldVal: T) => void): void;
201
  onMounted(callback: () => void): void;
202
  onBeforeUnmount(callback: () => void): void;
203
}
204

205
const hooks: AdapterHooks;
206
const isVue2: boolean;
207
const isVue3: boolean;
208
```
209

210
[Vue Framework Adapter](./adapter.md)
211

212
### Component Setup System
213

214
Standardized component setup functions for both template-based and renderless component patterns. Provides theme resolution, mode detection, and API composition.
215

216
```typescript { .api }
217
function setup<T>(config: SetupConfig<T>): SetupResult<T>;
218
function $setup(config: TemplateSetupConfig): ComponentSetupResult;
219

220
interface SetupConfig<T> {
221
  props: any;
222
  context: SetupContext;
223
  renderless: (props: any, hooks: AdapterHooks, utils: any) => T;
224
  api: string[];
225
  classes?: Record<string, string>;
226
}
227
```
228

229
[Component Setup System](./setup.md)
230

231
### Responsive Breakpoints
232

233
Reactive breakpoint detection system based on Tailwind CSS breakpoint specifications. Provides hooks for responsive component behavior.
234

235
```typescript { .api }
236
function useBreakpoint(): {
237
  current: Ref<'2xl' | 'xl' | 'lg' | 'md' | 'sm' | 'default'>;
238
};
239
```
240

241
[Responsive Breakpoints](./breakpoints.md)
242

243
### CSS Class Utilities
244

245
Comprehensive utilities for managing CSS classes including Tailwind CSS class merging, object/array stringification, and deduplication.
246

247
```typescript { .api }
248
function mergeClass(...cssClasses: CssClass[]): string;
249
function stringifyCssClass(cssClasses: CssClass[] | CssClass): string;
250
function stringifyCssClassObject(cssClassObject: CssClassObject): string;
251
function stringifyCssClassArray(cssClassArray: CssClassArray): string;
252
function deduplicateCssClass(cssClasses: CssClass[] | CssClass): string;
253

254
type CssClass = string | CssClassObject | CssClassArray;
255
interface CssClassObject {
256
  [key: string]: any;
257
}
258
type CssClassArray = Array<string | CssClassObject>;
259
```
260

261
[CSS Class Utilities](./css-utilities.md)
262

263
### Theme and Mode Resolution
264

265
Dynamic theme and mode resolution system supporting multiple themes (tiny/saas) and responsive modes (pc/mobile/mobile-first).
266

267
```typescript { .api }
268
function resolveMode(props: any, context: any): 'pc' | 'mobile' | 'mobile-first';
269
function resolveTheme(props: any, context: any): 'tiny' | 'saas';
270
```
271

272
[Theme and Mode Resolution](./theme-mode.md)
273

274
### SVG Icon System
275

276
SVG icon component creation with gradient icon support, unique ID generation, and responsive styling integration.
277

278
```typescript { .api }
279
function svg(config: SvgConfig): (propData?: any) => DefineComponent;
280

281
interface SvgConfig {
282
  name?: string;
283
  component: any;
284
}
285

286
const GRADIENT_ICONS_LIST: string[];
287
function generateIcon(vnode: any): void;
288
```
289

290
[SVG Icon System](./svg-icons.md)
291

292
### Design System Integration
293

294
Global design configuration system allowing component customization and theming integration across the component ecosystem.
295

296
```typescript { .api }
297
const design: {
298
  configKey: symbol;
299
  configInstance: any;
300
};
301

302
function provideDesignConfig(designConfig: DesignConfig): void;
303

304
const customDesignConfig: {
305
  designConfig: DesignConfig | null;
306
  twMerge: (str: string) => string;
307
};
308

309
function registerMcpConfig(mcpConfig: any, defineTool: any): void;
310

311
interface DesignConfig {
312
  components?: any;
313
  name?: string;
314
  version?: string;
315
}
316
```
317

318
[Design System Integration](./design-system.md)
319

320
## Types
321

322
```typescript { .api }
323
// Vue Framework Types
324
type PropType<T> = any;
325
type ExtractPropTypes<T> = any;
326
type DefineComponent = any;
327
type ComponentPublicInstance = any;
328
interface SetupContext {
329
  attrs: any;
330
  slots: any;
331
  emit: (...args: any[]) => void;
332
}
333
type ComputedRef<T> = {
334
  value: T;
335
};
336
type App = any;
337

338
// Component Props
339
const $props: {
340
  tiny_mode: StringConstructor;
341
  tiny_mode_root: BooleanConstructor;
342
  tiny_template: [FunctionConstructor, ObjectConstructor];
343
  tiny_renderless: FunctionConstructor;
344
  tiny_theme: StringConstructor;
345
  tiny_mcp_config: ObjectConstructor;
346
  tiny_chart_theme: ObjectConstructor;
347
};
348

349
const props: Array<
350
  | 'tiny_mode'
351
  | 'tiny_mode_root'
352
  | 'tiny_template'
353
  | 'tiny_renderless'
354
  | '_constants'
355
  | 'tiny_theme'
356
  | 'tiny_chart_theme'
357
  | 'tiny_mcp_config'
358
>;
359

360
// Component Setup Utilities
361
let setupComponent: Record<string, any>;
362
function initComponent(): void;
363
function $install(component: any): void;
364

365
// Constants
366
const $prefix: 'Tiny';
367
const version: string;
368
```