0
# Vue Facing Decorator
1

2
Vue Facing Decorator is a comprehensive Vue 3 class-based component system with TypeScript decorators, designed to replicate the functionality of vue-class-component and vue-property-decorator for Vue 3. It supports both stage 2 and stage 3 decorators, offers ES class inheritance with Vue extends and mixins, and transforms ES classes to Vue Option API according to specifications.
3

4
## Package Information
5

6
- **Package Name**: vue-facing-decorator
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vue-facing-decorator`
10
- **Peer Dependencies**: `vue@^3.0.0`
11
- **Dependencies**: `facing-metadata@^2.0.0`
12

13
## Core Imports
14

15
```typescript
16
import { Component, Setup, Ref, Watch, Prop, Emit, VModel } from "vue-facing-decorator";
17
```
18

19
Additional imports:
20
```typescript
21
import { Provide, Inject, Vanilla, Hook, createDecorator, TSX } from "vue-facing-decorator";
22
```
23

24
Base classes and utilities:
25
```typescript
26
import { ComponentBase, Base, mixins, toNative } from "vue-facing-decorator";
27
```
28

29
For CommonJS:
30
```javascript
31
const { Component, Setup, Ref, Watch, Prop, Emit, VModel } = require("vue-facing-decorator");
32
```
33

34
## Basic Usage
35

36
```typescript
37
import { Component, Setup, Ref, Watch, Prop, Emit } from "vue-facing-decorator";
38
import { ref } from "vue";
39

40
@Component
41
class MyComponent {
42
  // Props with validation
43
  @Prop({ type: String, required: true })
44
  title!: string;
45

46
  @Prop({ type: Number, default: 0 })
47
  count!: number;
48

49
  // Reactive data using setup
50
  @Setup(() => ref("Hello World"))
51
  message!: string;
52

53
  // Template refs
54
  @Ref()
55
  inputElement!: HTMLInputElement;
56

57
  // Watchers
58
  @Watch("count")
59
  onCountChange(newVal: number, oldVal: number) {
60
    console.log(`Count changed from ${oldVal} to ${newVal}`);
61
  }
62

63
  // Event emitters
64
  @Emit("update")
65
  emitUpdate() {
66
    return { message: this.message, count: this.count };
67
  }
68

69
  // Lifecycle hooks
70
  mounted() {
71
    this.inputElement?.focus();
72
  }
73

74
  // Methods
75
  increment() {
76
    this.count++;
77
    this.emitUpdate();
78
  }
79
}
80

81
export default toNative(MyComponent);
82
```
83

84
## Architecture
85

86
Vue Facing Decorator is built around several key components:
87

88
- **Class Decorators**: `@Component` transforms ES classes into Vue components with proper option mapping
89
- **Property Decorators**: Transform class properties into Vue's reactive system (props, refs, computed, etc.)
90
- **Method Decorators**: Handle watchers, event emitters, and lifecycle hooks
91
- **Base Classes**: `Base`/`Vue` provides inheritance foundation for component classes
92
- **Mixins System**: `mixins()` function enables composition of multiple component classes
93
- **TypeScript Integration**: Full type safety with stage 2 and stage 3 decorator support
94
- **Vue 3 Compatibility**: Seamless integration with Vue 3's Composition API and Option API
95

96
## Capabilities
97

98
### Core Component System
99

100
Foundation classes and decorators for creating Vue components from TypeScript classes.
101

102
```typescript { .api }
103
function Component(options?: ComponentOption): ClassDecorator;
104
const ComponentBase: (options?: ComponentOption) => ClassDecorator;
105
class Base { }
106
const Vue: typeof Base;
107
function toNative<T extends VueCons>(cons: T): T;
108
```
109

110
[Core Component System](./core-components.md)
111

112
### Property Decorators
113

114
Decorators for reactive properties, props, template references, and data binding.
115

116
```typescript { .api }
117
function Setup(setupFunction: OptionSetupFunction): PropertyDecorator;
118
function Ref(key?: string): PropertyDecorator;
119
function Prop(config?: PropsConfig): PropertyDecorator;
120
function VModel(config?: VModelConfig): PropertyDecorator;
121
const Model: typeof VModel;
122
function Vanilla(): PropertyDecorator;
123
```
124

125
[Property Decorators](./property-decorators.md)
126

127
### Method and Lifecycle Decorators
128

129
Decorators for watchers, event emitters, dependency injection, and lifecycle hooks.
130

131
```typescript { .api }
132
function Watch(key: string, options?: WatchOptions): MethodDecorator;
133
function Emit(eventName?: string): MethodDecorator;
134
function Provide(key?: string): PropertyDecorator;
135
function Inject(config?: InjectConfig): PropertyDecorator;
136
function Hook(): MethodDecorator;
137
```
138

139
[Method and Lifecycle Decorators](./method-lifecycle-decorators.md)
140

141
### Advanced Features
142

143
Mixins, custom decorators, TypeScript JSX support, and utility functions.
144

145
```typescript { .api }
146
function mixins<T extends VueCons[]>(...conses: T): MixedClass<T>;
147
function createDecorator(creator: Creator, options?: { preserve?: boolean }): PropertyDecorator;
148
function TSX<Properties, Events, IT>(): <C extends VueCons>(cons: C) => VueCons<InstanceType<C>, MergeIdentityType<IT, InstanceType<C>[typeof IdentitySymbol]>>;
149
```
150

151
[Advanced Features](./advanced-features.md)
152

153
## Core Types
154

155
```typescript { .api }
156
interface ComponentOption {
157
  name?: string;
158
  emits?: string[];
159
  provide?: Record<string, any> | Function;
160
  components?: Record<string, any>;
161
  directives?: Record<string, any>;
162
  inheritAttrs?: boolean;
163
  expose?: string[];
164
  render?: Function;
165
  template?: string;
166
  mixins?: any[];
167
  setup?: ComponentSetupFunction;
168
  methods?: MethodOptions;
169
  modifier?: (raw: any) => any;
170
  options?: ComponentCustomOptions & Record<string, any>;
171
}
172

173
interface PropsConfig {
174
  type?: any;
175
  required?: boolean;
176
  default?: any;
177
  validator?(value: any): boolean;
178
}
179

180
interface WatchOptions {
181
  flush?: 'post';
182
  deep?: boolean;
183
  immediate?: boolean;
184
}
185

186
interface InjectConfig {
187
  from?: string | symbol | Symbol | InjectionKey<any>;
188
  default?: any;
189
}
190

191
interface VModelConfig extends PropsConfig {
192
  name?: string;
193
}
194

195
type VueCons<RawInstance = Identity, IT = { props: {}, events: {} }> = {
196
  new(): ComponentPublicInstance & Identity<IT> & Omit<RawInstance, typeof IdentitySymbol>;
197
};
198
```
199

200
## Lifecycle Hook Interfaces
201

202
```typescript { .api }
203
interface HookBeforeCreate { beforeCreate(): void; }
204
interface HookCreated { created(): void; }
205
interface HookBeforeMount { beforeMount(): void; }
206
interface HookMounted { mounted(): void; }
207
interface HookBeforeUpdate { beforeUpdate(): void; }
208
interface HookUpdated { updated(): void; }
209
interface HookActivated { activated(): void; }
210
interface HookDeactivated { deactivated(): void; }
211
interface HookBeforeDestroy { beforeDestroy(): void; }
212
interface HookBeforeUnmount { beforeUnmount(): void; }
213
interface HookDestroyed { destroyed(): void; }
214
interface HookUnmounted { unmounted(): void; }
215
interface HookRenderTracked { renderTracked(): void; }
216
interface HookRenderTriggered { renderTriggered(): void; }
217
interface HookErrorCaptured { errorCaptured(): void; }
218
interface HookServerPrefetch { serverPrefetch(): void; }
219
interface HookRender { render(): void; }
220
```