0
# Props and Models
1

2
Enhanced props and model definition capabilities for Vue components.
3

4
## Capabilities
5

6
### Chain Call Props
7

8
Enhanced defineProps with method chaining syntax.
9

10
```typescript { .api }
11
/**
12
 * Chain call syntax for props with enhanced type inference
13
 */
14
declare const $defineProps: typeof definePropsChainCall;
15

16
/**
17
 * Enhanced defineProps with multiple syntax options
18
 */
19
declare const defineProps: DefineProps;
20

21
// Type definitions for chain call
22
interface DefinePropsChainCallOptions<T> {
23
  validator?: (value: T) => boolean;
24
  default?: T | (() => T);
25
  required?: boolean;
26
}
27

28
function definePropsChainCall<T>(): ChainCallProps<T>;
29

30
interface ChainCallProps<T> {
31
  [K in keyof T]: PropChain<T[K]>;
32
}
33

34
interface PropChain<T> {
35
  default(value: T | (() => T)): PropChain<T>;
36
  required(): PropChain<T>;
37
  validator(fn: (value: T) => boolean): PropChain<T>;
38
}
39
```
40

41
**Usage Examples:**
42

43
```vue
44
<script setup>
45
// Chain call syntax
46
const { 
47
  name,
48
  age,
49
  isActive 
50
} = $defineProps<{
51
  name: string;
52
  age: number;
53
  isActive: boolean;
54
}>()
55
  .name.required()
56
  .age.default(18).validator(age => age >= 0)
57
  .isActive.default(true);
58

59
// Alternative syntax
60
const props = defineProps({
61
  title: String,
62
  count: {
63
    type: Number,
64
    default: 0,
65
    validator: (value: number) => value >= 0,
66
  },
67
});
68
</script>
69
```
70

71
### Props Refs
72

73
Reactive references to props for easier composition.
74

75
```typescript { .api }
76
/**
77
 * Create reactive references to all props
78
 * @returns Object with ref wrappers for each prop
79
 */
80
declare function definePropsRefs<T>(): PropsRefs<T>;
81

82
/**
83
 * Create reactive references with default values
84
 * @param defaults - Default values for props
85
 * @returns Object with ref wrappers for each prop
86
 */
87
declare function definePropsRefs<T>(defaults: Partial<T>): PropsRefs<T>;
88

89
// Utility types
90
type PropsRefs<T> = {
91
  [K in keyof T]: Ref<T[K]>;
92
};
93

94
// For default value handling
95
declare const withDefaults: {
96
  definePropsRefs: typeof withDefaultsDefinePropsRefs;
97
};
98

99
function withDefaultsDefinePropsRefs<T>(
100
  props: PropsRefs<T>,
101
  defaults: Partial<T>
102
): PropsRefs<T>;
103
```
104

105
**Usage Examples:**
106

107
```vue
108
<script setup>
109
// Basic props refs
110
const {
111
  nameRef,
112
  ageRef,
113
  configRef
114
} = definePropsRefs<{
115
  name: string;
116
  age: number;
117
  config: { theme: string };
118
}>();
119

120
// With defaults
121
const propsRefs = withDefaults(definePropsRefs<{
122
  title: string;
123
  count: number;
124
  enabled: boolean;
125
}>(), {
126
  count: 0,
127
  enabled: true,
128
});
129

130
// Reactive access
131
watchEffect(() => {
132
  console.log('Name changed:', nameRef.value);
133
});
134

135
// Computed based on props
136
const displayName = computed(() => 
137
  `${nameRef.value} (${ageRef.value})`
138
);
139
</script>
140
```
141

142
### Individual Prop Definition
143

144
Define single props with validation and defaults.
145

146
```typescript { .api }
147
/**
148
 * Define individual prop with validation and defaults
149
 * @param name - Prop name
150
 * @param options - Prop configuration options
151
 * @returns Reactive prop value
152
 */
153
declare function defineProp<T>(
154
  name: string, 
155
  options?: PropOptions<T>
156
): T;
157

158
/**
159
 * Define prop with default value
160
 * @param name - Prop name  
161
 * @param defaultValue - Default value
162
 * @returns Reactive prop value
163
 */
164
declare function defineProp<T>(
165
  name: string,
166
  defaultValue: T
167
): T;
168

169
interface PropOptions<T> {
170
  type?: PropType<T>;
171
  required?: boolean;
172
  default?: T | (() => T);
173
  validator?: (value: T) => boolean;
174
}
175

176
type PropType<T> = 
177
  | (() => T)
178
  | (new (...args: any[]) => T)
179
  | (new (...args: string[]) => Function)
180
  | PropType<T>[]
181
  | null;
182
```
183

184
**Usage Examples:**
185

186
```vue
187
<script setup>
188
// Simple prop with default
189
const title = defineProp("title", "Default Title");
190

191
// Prop with validation
192
const age = defineProp("age", {
193
  type: Number,
194
  required: true,
195
  validator: (value: number) => value >= 0 && value <= 120,
196
});
197

198
// Prop with factory default
199
const config = defineProp("config", {
200
  type: Object,
201
  default: () => ({ theme: "light" }),
202
});
203

204
// Optional prop
205
const description = defineProp<string | undefined>("description");
206
</script>
207
```
208

209
### Models Definition
210

211
Enhanced model definition with multiple v-model support.
212

213
```typescript { .api }
214
/**
215
 * Define multiple models for component
216
 * @returns Object with model refs
217
 */
218
declare function defineModels<T extends Record<string, any>>(): Models<T>;
219

220
/**
221
 * Define models with validation and defaults
222
 * @param options - Model configuration options
223
 * @returns Object with model refs
224
 */
225
declare function defineModels<T extends Record<string, any>>(
226
  options: ModelsOptions<T>
227
): Models<T>;
228

229
// Utility types
230
type Models<T> = {
231
  [K in keyof T]: WritableComputedRef<T[K]>;
232
};
233

234
type ModelsOptions<T> = {
235
  [K in keyof T]?: {
236
    get?: (value: T[K]) => T[K];
237
    set?: (value: T[K]) => T[K];
238
    default?: T[K] | (() => T[K]);
239
  };
240
};
241

242
// Individual model definition
243
declare function defineModel<T>(): WritableComputedRef<T>;
244
declare function defineModel<T>(name: string): WritableComputedRef<T>;
245
declare function defineModel<T>(
246
  name: string, 
247
  options: ModelOptions<T>
248
): WritableComputedRef<T>;
249

250
interface ModelOptions<T> {
251
  get?: (value: T) => T;
252
  set?: (value: T) => T;
253
  default?: T | (() => T);
254
}
255
```
256

257
**Usage Examples:**
258

259
```vue
260
<script setup>
261
// Multiple models
262
const {
263
  modelValue,
264
  checked,
265
  selectedId
266
} = defineModels<{
267
  modelValue: string;
268
  checked: boolean;
269
  selectedId: number;
270
}>();
271

272
// Individual models
273
const value = defineModel<string>();
274
const isOpen = defineModel<boolean>("open");
275

276
// Model with transformation
277
const displayValue = defineModel("display", {
278
  get: (value: string) => value.toUpperCase(),
279
  set: (value: string) => value.toLowerCase(),
280
});
281

282
// Model with default
283
const count = defineModel("count", {
284
  default: 0,
285
});
286

287
// Usage in template and script
288
function increment() {
289
  count.value++;
290
}
291

292
function toggle() {
293
  checked.value = !checked.value;
294
}
295
</script>
296

297
<template>
298
  <input v-model="modelValue" />
299
  <input type="checkbox" v-model="checked" />
300
  <select v-model="selectedId">
301
    <option value="1">Option 1</option>
302
    <option value="2">Option 2</option>
303
  </select>
304
</template>
305
```
306

307
### Enhanced Props Definition
308

309
Extended defineProps with additional features.
310

311
```typescript { .api }
312
/**
313
 * Enhanced defineProps with multiple syntax options
314
 */
315
interface DefineProps {
316
  <T>(): T;
317
  <T>(props: T): T;
318
  <T, D>(props: T, defaults: D): T & D;
319
}
320

321
// Props with runtime validation
322
declare function defineProps<T>(
323
  runtimeProps: RuntimeProps<T>
324
): T;
325

326
type RuntimeProps<T> = {
327
  [K in keyof T]: PropDefinition<T[K]>;
328
};
329

330
type PropDefinition<T> = 
331
  | PropConstructor<T>
332
  | PropValidation<T>;
333

334
interface PropValidation<T> {
335
  type?: PropConstructor<T> | PropConstructor<T>[];
336
  required?: boolean;
337
  default?: T | (() => T);
338
  validator?: (value: T) => boolean;
339
}
340

341
type PropConstructor<T> = 
342
  | { new (...args: any[]): T }
343
  | { (): T }
344
  | PropMethod<T>;
345

346
type PropMethod<T> = T extends string
347
  ? StringConstructor
348
  : T extends number
349
  ? NumberConstructor  
350
  : T extends boolean
351
  ? BooleanConstructor
352
  : T extends any[]
353
  ? ArrayConstructor
354
  : T extends object
355
  ? ObjectConstructor
356
  : T extends (...args: any[]) => any
357
  ? FunctionConstructor
358
  : any;
359
```
360

361
## Type Definitions
362

363
Complete TypeScript support for props and models.
364

365
```typescript { .api }
366
// Utility types for props transformation
367
type RequiredKeys<T> = {
368
  [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
369
}[keyof T];
370

371
type OptionalKeys<T> = {
372
  [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
373
}[keyof T];
374

375
// Props extraction
376
type ExtractPropTypes<O> = {
377
  [K in keyof O]: InferPropType<O[K]>;
378
};
379

380
type InferPropType<T> = T extends null
381
  ? any
382
  : T extends { type: null | true }
383
  ? any
384
  : T extends ObjectConstructor | { type: ObjectConstructor }
385
  ? Record<string, any>
386
  : T extends BooleanConstructor | { type: BooleanConstructor }
387
  ? boolean
388
  : T extends Prop<infer V, infer D>
389
  ? unknown extends V
390
    ? D
391
    : V
392
  : T;
393

394
// Prop definition helper
395
interface Prop<T, D = T> {
396
  (): T;
397
  new (...args: any[]): T;
398
  readonly prototype: T;
399
}
400

401
// Default value handling
402
type DefaultValue<T, D> = D extends Record<string, any> | Array<any>
403
  ? () => D
404
  : D;
405
```