CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-unplugin-vue-macros

Explore more macros and syntax sugar to Vue.

Pending
Overview
Eval results
Files

props-models.mddocs/

Props and Models

Enhanced props and model definition capabilities for Vue components.

Capabilities

Chain Call Props

Enhanced defineProps with method chaining syntax.

/**
 * Chain call syntax for props with enhanced type inference
 */
declare const $defineProps: typeof definePropsChainCall;

/**
 * Enhanced defineProps with multiple syntax options
 */
declare const defineProps: DefineProps;

// Type definitions for chain call
interface DefinePropsChainCallOptions<T> {
  validator?: (value: T) => boolean;
  default?: T | (() => T);
  required?: boolean;
}

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

interface ChainCallProps<T> {
  [K in keyof T]: PropChain<T[K]>;
}

interface PropChain<T> {
  default(value: T | (() => T)): PropChain<T>;
  required(): PropChain<T>;
  validator(fn: (value: T) => boolean): PropChain<T>;
}

Usage Examples:

<script setup>
// Chain call syntax
const { 
  name,
  age,
  isActive 
} = $defineProps<{
  name: string;
  age: number;
  isActive: boolean;
}>()
  .name.required()
  .age.default(18).validator(age => age >= 0)
  .isActive.default(true);

// Alternative syntax
const props = defineProps({
  title: String,
  count: {
    type: Number,
    default: 0,
    validator: (value: number) => value >= 0,
  },
});
</script>

Props Refs

Reactive references to props for easier composition.

/**
 * Create reactive references to all props
 * @returns Object with ref wrappers for each prop
 */
declare function definePropsRefs<T>(): PropsRefs<T>;

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

// Utility types
type PropsRefs<T> = {
  [K in keyof T]: Ref<T[K]>;
};

// For default value handling
declare const withDefaults: {
  definePropsRefs: typeof withDefaultsDefinePropsRefs;
};

function withDefaultsDefinePropsRefs<T>(
  props: PropsRefs<T>,
  defaults: Partial<T>
): PropsRefs<T>;

Usage Examples:

<script setup>
// Basic props refs
const {
  nameRef,
  ageRef,
  configRef
} = definePropsRefs<{
  name: string;
  age: number;
  config: { theme: string };
}>();

// With defaults
const propsRefs = withDefaults(definePropsRefs<{
  title: string;
  count: number;
  enabled: boolean;
}>(), {
  count: 0,
  enabled: true,
});

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

// Computed based on props
const displayName = computed(() => 
  `${nameRef.value} (${ageRef.value})`
);
</script>

Individual Prop Definition

Define single props with validation and defaults.

/**
 * Define individual prop with validation and defaults
 * @param name - Prop name
 * @param options - Prop configuration options
 * @returns Reactive prop value
 */
declare function defineProp<T>(
  name: string, 
  options?: PropOptions<T>
): T;

/**
 * Define prop with default value
 * @param name - Prop name  
 * @param defaultValue - Default value
 * @returns Reactive prop value
 */
declare function defineProp<T>(
  name: string,
  defaultValue: T
): T;

interface PropOptions<T> {
  type?: PropType<T>;
  required?: boolean;
  default?: T | (() => T);
  validator?: (value: T) => boolean;
}

type PropType<T> = 
  | (() => T)
  | (new (...args: any[]) => T)
  | (new (...args: string[]) => Function)
  | PropType<T>[]
  | null;

Usage Examples:

<script setup>
// Simple prop with default
const title = defineProp("title", "Default Title");

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

// Prop with factory default
const config = defineProp("config", {
  type: Object,
  default: () => ({ theme: "light" }),
});

// Optional prop
const description = defineProp<string | undefined>("description");
</script>

Models Definition

Enhanced model definition with multiple v-model support.

/**
 * Define multiple models for component
 * @returns Object with model refs
 */
declare function defineModels<T extends Record<string, any>>(): Models<T>;

/**
 * Define models with validation and defaults
 * @param options - Model configuration options
 * @returns Object with model refs
 */
declare function defineModels<T extends Record<string, any>>(
  options: ModelsOptions<T>
): Models<T>;

// Utility types
type Models<T> = {
  [K in keyof T]: WritableComputedRef<T[K]>;
};

type ModelsOptions<T> = {
  [K in keyof T]?: {
    get?: (value: T[K]) => T[K];
    set?: (value: T[K]) => T[K];
    default?: T[K] | (() => T[K]);
  };
};

// Individual model definition
declare function defineModel<T>(): WritableComputedRef<T>;
declare function defineModel<T>(name: string): WritableComputedRef<T>;
declare function defineModel<T>(
  name: string, 
  options: ModelOptions<T>
): WritableComputedRef<T>;

interface ModelOptions<T> {
  get?: (value: T) => T;
  set?: (value: T) => T;
  default?: T | (() => T);
}

Usage Examples:

<script setup>
// Multiple models
const {
  modelValue,
  checked,
  selectedId
} = defineModels<{
  modelValue: string;
  checked: boolean;
  selectedId: number;
}>();

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

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

// Model with default
const count = defineModel("count", {
  default: 0,
});

// Usage in template and script
function increment() {
  count.value++;
}

function toggle() {
  checked.value = !checked.value;
}
</script>

<template>
  <input v-model="modelValue" />
  <input type="checkbox" v-model="checked" />
  <select v-model="selectedId">
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
  </select>
</template>

Enhanced Props Definition

Extended defineProps with additional features.

/**
 * Enhanced defineProps with multiple syntax options
 */
interface DefineProps {
  <T>(): T;
  <T>(props: T): T;
  <T, D>(props: T, defaults: D): T & D;
}

// Props with runtime validation
declare function defineProps<T>(
  runtimeProps: RuntimeProps<T>
): T;

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

type PropDefinition<T> = 
  | PropConstructor<T>
  | PropValidation<T>;

interface PropValidation<T> {
  type?: PropConstructor<T> | PropConstructor<T>[];
  required?: boolean;
  default?: T | (() => T);
  validator?: (value: T) => boolean;
}

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

type PropMethod<T> = T extends string
  ? StringConstructor
  : T extends number
  ? NumberConstructor  
  : T extends boolean
  ? BooleanConstructor
  : T extends any[]
  ? ArrayConstructor
  : T extends object
  ? ObjectConstructor
  : T extends (...args: any[]) => any
  ? FunctionConstructor
  : any;

Type Definitions

Complete TypeScript support for props and models.

// Utility types for props transformation
type RequiredKeys<T> = {
  [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
}[keyof T];

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

// Props extraction
type ExtractPropTypes<O> = {
  [K in keyof O]: InferPropType<O[K]>;
};

type InferPropType<T> = T extends null
  ? any
  : T extends { type: null | true }
  ? any
  : T extends ObjectConstructor | { type: ObjectConstructor }
  ? Record<string, any>
  : T extends BooleanConstructor | { type: BooleanConstructor }
  ? boolean
  : T extends Prop<infer V, infer D>
  ? unknown extends V
    ? D
    : V
  : T;

// Prop definition helper
interface Prop<T, D = T> {
  (): T;
  new (...args: any[]): T;
  readonly prototype: T;
}

// Default value handling
type DefaultValue<T, D> = D extends Record<string, any> | Array<any>
  ? () => D
  : D;

Install with Tessl CLI

npx tessl i tessl/npm-unplugin-vue-macros

docs

advanced-features.md

component-definition.md

configuration.md

index.md

props-models.md

syntax-sugar.md

tile.json