@stacksjs/stx
Version:
A performant UI Framework. Powered by Bun.
199 lines • 5.69 kB
TypeScript
/**
* Define component props with type safety and validation.
*
* @example
* ```typescript
* // Simple usage with types only
* const props = defineProps<{
* title: string
* count: number
* }>()
*
* // With validation and defaults
* const props = defineProps<{
* title: string
* count?: number
* status: 'active' | 'inactive'
* }>({
* title: { required: true },
* count: { default: 0 },
* status: {
* default: 'active',
* validator: (v) => ['active', 'inactive'].includes(v)
* }
* })
* ```
*/
export declare function defineProps<T extends Record<string, unknown>>(definitions?: PropsDefinition<T>): T;
/**
* Define props with runtime validation.
* Use this when you need validation errors at runtime.
*/
export declare function definePropsWithValidation<T extends Record<string, unknown>>(definitions: PropsDefinition<T>, options?: {
componentName?: string
throwOnError?: boolean
logWarnings?: boolean
}): { props: T; validation: PropValidationResult };
/**
* Define default values for props.
*
* @example
* ```typescript
* const props = withDefaults(defineProps<{
* title: string
* count?: number
* items?: string[]
* }>(), {
* count: 0,
* items: () => []
* })
* ```
*/
export declare function withDefaults<T extends Record<string, unknown>>(props: T, defaults: Partial<{ [K in keyof T]: T[K] | (() => T[K]) }>): T;
/**
* Create a prop type definition for a specific type.
*/
export declare function prop<T>(options: PropOptions<T>): PropOptions<T>;
/**
* Create a required prop.
*/
export declare function required<T>(type?: PropType<T>): PropOptions<T>;
/**
* Create an optional prop with default.
*/
export declare function optional<T>(defaultValue: T | (() => T), type?: PropType<T>): PropOptions<T>;
/**
* Create a prop with a validator.
*/
export declare function validated<T>(validator: (value: T) => boolean, options?: Omit<PropOptions<T>, 'validator'>): PropOptions<T>;
/**
* Create a prop that accepts one of specific values.
*/
export declare function oneOf<T extends string | number>(values: readonly T[], options?: Omit<PropOptions<T>, 'validator'>): PropOptions<T>;
/**
* Create a prop for array of specific type.
*/
export declare function arrayOf<T>(_itemType: PropType<T>, options?: Omit<PropOptions<T[]>, 'type'>): PropOptions<T[]>;
/**
* Create a prop for object with specific shape.
*/
export declare function shape<T extends Record<string, unknown>>(_shape: PropsDefinition<T>, options?: Omit<PropOptions<T>, 'type'>): PropOptions<T>;
/**
* Process props passed to a component.
* Called internally during component rendering.
*/
export declare function processComponentProps(rawProps: Record<string, unknown>, definitions?: PropsDefinition<Record<string, unknown>>, componentName?: string): Record<string, unknown>;
/**
* Define component events (emits).
*
* @example
* ```typescript
* const emit = defineEmits<{
* 'update:value': string
* 'submit': { data: FormData }
* 'close': void
* }>()
*
* // Usage
* emit('update:value', 'new value')
* emit('submit', { data: formData })
* emit('close', undefined)
* ```
*/
export declare function defineEmits<E extends Record<string, unknown>>(): EmitFn<E>;
/**
* Expose component methods/properties to parent.
*
* @example
* ```typescript
* defineExpose({
* focus: () => inputRef.value?.focus(),
* reset: () => { value = '' },
* value: computed(() => internalValue)
* })
* ```
*/
export declare function defineExpose<T extends Record<string, unknown>>(exposed: T): void;
/**
* Generate TypeScript interface from prop definitions.
* Useful for documentation and type generation.
*/
export declare function generatePropsInterface(componentName: string, definitions: PropsDefinition<Record<string, unknown>>): string;
/** Prop definition options */
export declare interface PropOptions<T = unknown> {
type?: PropType<T> | PropType<T>[]
required?: boolean
default?: T | (() => T)
validator?: (value: T) => boolean
description?: string
}
/** Prop validation error */
export declare interface PropValidationError {
prop: string
message: string
value: unknown
expected?: string
}
/** Prop validation result */
export declare interface PropValidationResult {
valid: boolean
errors: PropValidationError[]
warnings: string[]
}
/**
* STX Props System
*
* Provides type-safe component props with runtime validation.
*
* @module props
*
* @example
* ```html
* <script>
* import { defineProps } from 'stx'
*
* const props = defineProps<{
* title: string
* count?: number
* items: string[]
* }>({
* title: { required: true },
* count: { default: 0 },
* items: { default: () => [] }
* })
* </script>
*
* <h1>{{ props.title }}</h1>
* <p>Count: {{ props.count }}</p>
* ```
*/
/** Supported prop types */
export type PropType<T> = | StringConstructor
| NumberConstructor
| BooleanConstructor
| ArrayConstructor
| ObjectConstructor
| FunctionConstructor
| DateConstructor
| SymbolConstructor
| { new (...args: unknown[]): T }
| PropType<T>[]
/** Props definition object */
export type PropsDefinition<T> = {
[K in keyof T]?: PropOptions<T[K]> | PropType<T[K]>
}
/** Extracted prop types */
export type ExtractPropTypes<T extends PropsDefinition<unknown>> = {
[K in keyof T]: T[K] extends PropOptions<infer V>
? V
: T[K] extends PropType<infer V>
? V
: unknown
}
/** Event handler type */
export type EventHandler<T = unknown> = (payload: T) => void
/** Emit function type */
export type EmitFn<E extends Record<string, unknown>> = <K extends keyof E>(
event: K,
payload: E[K],
) => void