0
# Component Setup System
1

2
The Component Setup System provides standardized component setup functions for both template-based and renderless component patterns. It handles theme resolution, mode detection, API composition, and design system integration.
3

4
## Capabilities
5

6
### Renderless Component Setup
7

8
The main setup function for renderless components that provides API composition, theme resolution, and utility integration.
9

10
```typescript { .api }
11
/**
12
 * Setup function for renderless components with API composition
13
 * @param config - Setup configuration object
14
 * @returns Setup result with composed APIs and utilities
15
 */
16
function setup<T>(config: SetupConfig<T>): SetupResult<T>;
17

18
interface SetupConfig<T> {
19
  /** Component props */
20
  props: any;
21
  /** Component setup context */
22
  context: SetupContext;
23
  /** Renderless function that defines component logic */
24
  renderless: (props: any, hooks: AdapterHooks, utils: any, extendOptions?: any) => T;
25
  /** Array of API method names to expose */
26
  api: string[];
27
  /** Extended options for renderless function */
28
  extendOptions?: any;
29
  /** Whether component is single-layer (mono) */
30
  mono?: boolean;
31
  /** CSS class definitions */
32
  classes?: Record<string, string>;
33
}
34

35
interface SetupResult<T> {
36
  /** Translation function */
37
  t: (key: string) => string;
38
  /** Component instance */
39
  vm: any;
40
  /** Filter function for attributes */
41
  f: typeof bindFilter;
42
  /** Attribute filter function */
43
  a: typeof filterAttrs;
44
  /** Define instance properties */
45
  d: (props: any) => void;
46
  /** Define parent instance properties */
47
  dp: (props: any) => void;
48
  /** Get CSS class by key */
49
  gcls: (key: string) => string;
50
  /** Merge CSS classes */
51
  m: typeof mergeClass;
52
  /** Slots getter */
53
  slots: any;
54
  /** Scoped slots getter */
55
  scopedSlots: any;
56
  /** Exposed API methods */
57
  [key: string]: any;
58
}
59
```
60

61
**Usage Examples:**
62

63
```typescript
64
import { setup } from "@opentiny/vue-common";
65

66
// Basic renderless component setup
67
export default {
68
  setup(props, context) {
69
    return setup({
70
      props,
71
      context,
72
      renderless: (props, hooks, utils) => {
73
        const state = hooks.ref({ count: 0 });
74
        
75
        const handleClick = () => {
76
          state.value.count++;
77
        };
78
        
79
        return {
80
          state,
81
          handleClick
82
        };
83
      },
84
      api: ['state', 'handleClick'],
85
      classes: {
86
        button: 'tiny-button',
87
        wrapper: 'tiny-wrapper'
88
      }
89
    });
90
  }
91
};
92
```
93

94
### Template Component Setup
95

96
Setup function for template-based components that handles dynamic template resolution and design system integration.
97

98
```typescript { .api }
99
/**
100
 * Setup function for template-based components
101
 * @param config - Template setup configuration
102
 * @returns Component setup result with template resolution
103
 */
104
function $setup(config: TemplateSetupConfig): ComponentSetupResult;
105

106
interface TemplateSetupConfig {
107
  /** Component props */
108
  props: any;
109
  /** Component setup context */
110
  context: SetupContext;
111
  /** Template function that returns component based on mode */
112
  template: (mode: string, props: any) => any;
113
  /** Extended configuration */
114
  extend?: any;
115
}
116

117
interface ComponentSetupResult {
118
  /** Resolved view component */
119
  view: ComputedRef<any>;
120
  /** Component mode */
121
  mode: string;
122
  /** Design configuration */
123
  designConfig: any;
124
  /** Custom design props */
125
  customDesignProps: any;
126
}
127
```
128

129
**Usage Examples:**
130

131
```typescript
132
import { $setup } from "@opentiny/vue-common";
133

134
// Template-based component setup
135
export default {
136
  setup(props, context) {
137
    return $setup({
138
      props,
139
      context,
140
      template: (mode, props) => {
141
        if (mode === 'mobile') {
142
          return () => import('./mobile-template.vue');
143
        }
144
        return () => import('./pc-template.vue');
145
      }
146
    });
147
  }
148
};
149
```
150

151
### Component Plugin Installation
152

153
Utility for adding Vue plugin installation method to components.
154

155
```typescript { .api }
156
/**
157
 * Add Vue plugin install method to component
158
 * @param component - Component to add install method to
159
 */
160
function $install(component: any): void;
161
```
162

163
**Usage Examples:**
164

165
```typescript
166
import { $install } from "@opentiny/vue-common";
167

168
const MyComponent = {
169
  name: 'TinyMyComponent',
170
  // ... component definition
171
};
172

173
// Add plugin installation capability
174
$install(MyComponent);
175

176
// Now component can be installed as a plugin
177
app.use(MyComponent);
178
```
179

180
### Component Initialization
181

182
Global component initialization system for managing component lifecycle.
183

184
```typescript { .api }
185
/**
186
 * Mutable exports for component setup
187
 */
188
let setupComponent: Record<string, any>;
189

190
/**
191
 * Initialize all registered components
192
 * Calls install() and init() methods on registered components
193
 */
194
function initComponent(): void;
195
```
196

197
**Usage Examples:**
198

199
```typescript
200
import { setupComponent, initComponent } from "@opentiny/vue-common";
201

202
// Register a component for initialization
203
setupComponent.MyComponent = {
204
  install(app) {
205
    app.component('TinyMyComponent', MyComponent);
206
  },
207
  init(properties) {
208
    // Initialize component with global properties
209
  }
210
};
211

212
// Initialize all registered components
213
initComponent();
214
```
215

216
### Attribute Filtering
217

218
Utility for filtering component attributes based on inclusion/exclusion patterns.
219

220
```typescript { .api }
221
/**
222
 * Filter component attributes based on patterns
223
 * @param attrs - Component attributes object
224
 * @param filters - Array of filter patterns (regex strings)
225
 * @param include - Whether to include (true) or exclude (false) matching attributes
226
 * @returns Filtered attributes object
227
 */
228
function filterAttrs(
229
  attrs: Record<string, any>, 
230
  filters: string[], 
231
  include?: boolean
232
): Record<string, any>;
233
```
234

235
**Usage Examples:**
236

237
```typescript
238
import { filterAttrs } from "@opentiny/vue-common";
239

240
// Include only specific attributes
241
const allowedAttrs = filterAttrs(
242
  $attrs, 
243
  ['class', 'style', 'title', 'id'], 
244
  true // include mode
245
);
246

247
// Exclude event handlers
248
const nonEventAttrs = filterAttrs(
249
  $attrs,
250
  ['^on[A-Z]'], // regex pattern for event handlers
251
  false // exclude mode
252
);
253
```
254

255
### Deferred Rendering
256

257
Performance optimization hook for progressive component rendering.
258

259
```typescript { .api }
260
/**
261
 * Create deferred rendering controller
262
 * @param maxCount - Maximum frame count (default: 100)
263
 * @returns Deferred rendering controller
264
 */
265
function useDefer(maxCount?: number): {
266
  /** Check if rendering should be deferred for given frame */
267
  defer(n: number): boolean;
268
  /** Reset frame counter */
269
  reset(): void;
270
  /** Cancel animation frames */
271
  cancel(): void;
272
};
273
```
274

275
**Usage Examples:**
276

277
```typescript
278
import { useDefer } from "@opentiny/vue-common";
279

280
export default {
281
  setup() {
282
    const deferrer = useDefer(50);
283
    
284
    return {
285
      // Render expensive component only after 10 frames
286
      shouldRenderExpensive: () => deferrer.defer(10),
287
      // Render less expensive component after 5 frames  
288
      shouldRenderNormal: () => deferrer.defer(5)
289
    };
290
  }
291
};
292
```
293

294
## Design System Integration
295

296
### Design Configuration
297

298
Global design configuration system for component customization.
299

300
```typescript { .api }
301
/**
302
 * Design configuration object
303
 */
304
const design: {
305
  /** Symbol key for dependency injection */
306
  configKey: symbol;
307
  /** Global design configuration instance */
308
  configInstance: any;
309
};
310

311
/**
312
 * Provide design configuration to component tree
313
 * @param designConfig - Design configuration object
314
 */
315
function provideDesignConfig(designConfig: DesignConfig): void;
316

317
interface DesignConfig {
318
  /** Component-specific configurations */
319
  components?: Record<string, any>;
320
  /** Design system name */
321
  name?: string;
322
  /** Design system version */
323
  version?: string;
324
}
325
```
326

327
### Custom Design Configuration
328

329
Support for custom design configurations (e.g., MetaERP integration).
330

331
```typescript { .api }
332
/**
333
 * Custom design configuration for external systems
334
 */
335
const customDesignConfig: {
336
  /** Design configuration instance */
337
  designConfig: DesignConfig | null;
338
  /** Tailwind merge function */
339
  twMerge: (str: string) => string;
340
};
341
```
342

343
## MCP Integration
344

345
### MCP Configuration Registration
346

347
Multi-Component Platform (MCP) configuration system for advanced component integration.
348

349
```typescript { .api }
350
/**
351
 * Register MCP configuration and tools
352
 * @param mcpConfig - MCP configuration object
353
 * @param defineTool - Tool definition function
354
 */
355
function registerMcpConfig(mcpConfig: any, defineTool: any): void;
356
```
357

358
## Constants and Props
359

360
### Standard Component Props
361

362
Standardized props that all TinyVue components support.
363

364
```typescript { .api }
365
/**
366
 * Standard component props object
367
 */
368
const $props: {
369
  tiny_mode: StringConstructor;
370
  tiny_mode_root: BooleanConstructor;
371
  tiny_template: [FunctionConstructor, ObjectConstructor];
372
  tiny_renderless: FunctionConstructor;
373
  tiny_theme: StringConstructor;
374
  tiny_mcp_config: ObjectConstructor;
375
  tiny_chart_theme: ObjectConstructor;
376
};
377

378
/**
379
 * Array of standard prop names
380
 */
381
const props: Array<
382
  | 'tiny_mode'
383
  | 'tiny_mode_root'  
384
  | 'tiny_template'
385
  | 'tiny_renderless'
386
  | '_constants'
387
  | 'tiny_theme'
388
  | 'tiny_chart_theme'
389
  | 'tiny_mcp_config'
390
>;
391

392
/**
393
 * Component name prefix
394
 */
395
const $prefix: 'Tiny';
396
```