@stacksjs/stx
Version:
A performant UI Framework. Powered by Bun.
253 lines • 6.93 kB
TypeScript
/**
* Set the current component instance for lifecycle hook registration.
*/
export declare function setCurrentInstance(instance: ComponentInstance | null): void;
/**
* Get the current component instance.
*/
export declare function getCurrentInstance(): ComponentInstance | null;
/**
* Create a new component instance.
*/
export declare function createComponentInstance(): ComponentInstance;
/**
* Create a new reactive scope.
*/
export declare function createScope(): ReactiveScope;
/**
* Create a reactive reference.
*
* @example
* ```typescript
* const count = ref(0)
* count.value++
* console.log(count.value) // 1
* ```
*/
export declare function ref<T>(initialValue: T): Ref<T>;
/**
* Create a reactive object (proxy-based).
*
* @example
* ```typescript
* const state = reactive({ count: 0, name: 'STX' })
* state.count++
* state.name = 'Vue-style STX'
* ```
*/
export declare function reactive<T extends object>(target: T): T;
/**
* Create a computed value.
*
* @example
* ```typescript
* const count = ref(0)
* const doubled = computed(() => count.value * 2)
* console.log(doubled.value) // 0
* count.value = 5
* console.log(doubled.value) // 10
* ```
*/
export declare function computed<T>(getter: () => T): Ref<T>;
/**
* Watch a reactive source and run a callback on changes.
*
* @example
* ```typescript
* const count = ref(0)
*
* watch(count, (newVal, oldVal) => {
* console.log(`Changed from ${oldVal} to ${newVal}`)
* })
*
* // With options
* watch(count, callback, { immediate: true, deep: true })
* ```
*/
export declare function watch<T>(source: Ref<T> | (() => T), callback: WatchCallback<T>, options?: WatchOptions): () => void;
/**
* Watch multiple sources.
*
* @example
* ```typescript
* const count = ref(0)
* const name = ref('STX')
*
* watch([count, name], ([newCount, newName], [oldCount, oldName]) => {
* console.log(`Count: ${oldCount} -> ${newCount}`)
* console.log(`Name: ${oldName} -> ${newName}`)
* })
* ```
*/
export declare function watchMultiple<T extends readonly Ref<unknown>[]>(sources: T, callback: (
newValues: { [K in keyof T]: T[K] extends Ref<infer V> ? V : never },
oldValues: { [K in keyof T]: T[K] extends Ref<infer V> ? V : never },
) => void, options?: WatchOptions): () => void;
/**
* Automatically track reactive dependencies and re-run on changes.
*
* @example
* ```typescript
* const count = ref(0)
*
* watchEffect(() => {
* console.log(`Count is: ${count.value}`)
* })
* ```
*/
export declare function watchEffect(effect: () => void | (() => void)): () => void;
/**
* Register a callback to run before component mounts.
*/
export declare function onBeforeMount(callback: LifecycleHook): void;
/**
* Register a callback to run when component is mounted to DOM.
*
* @example
* ```typescript
* onMounted(async () => {
* const data = await fetch('/api/data').then(r => r.json())
* items.value = data
* })
* ```
*/
export declare function onMounted(callback: LifecycleHook): void;
/**
* Register a callback to run before component updates.
*/
export declare function onBeforeUpdate(callback: LifecycleHook): void;
/**
* Register a callback to run after component updates.
*/
export declare function onUpdated(callback: LifecycleHook): void;
/**
* Register a callback to run before component unmounts.
*/
export declare function onBeforeUnmount(callback: LifecycleHook): void;
/**
* Register a callback to run after component unmounts.
* Use this for cleanup: removing event listeners, clearing timers, etc.
*
* @example
* ```typescript
* let interval: number
*
* onMounted(() => {
* interval = setInterval(refresh, 5000)
* })
*
* onUnmounted(() => {
* clearInterval(interval)
* })
* ```
*/
export declare function onUnmounted(callback: LifecycleHook): void;
/**
* Run all hooks of a specific type for an instance.
*/
export declare function runHooks(instance: ComponentInstance, hookName: keyof ComponentInstance['hooks']): Promise<void>;
/**
* Mount a component instance.
*/
export declare function mountInstance(instance: ComponentInstance): Promise<void>;
/**
* Update a component instance.
*/
export declare function updateInstance(instance: ComponentInstance): Promise<void>;
/**
* Unmount a component instance.
*/
export declare function unmountInstance(instance: ComponentInstance): Promise<void>;
/**
* Generate the client-side runtime script.
* This is injected into the page to enable reactivity.
*/
export declare function generateClientRuntime(): string;
/**
* Vue-Style Reactivity Module
*
* Provides Vue 3 Composition API-style reactivity for STX templates.
* This module is designed to feel familiar to Vue developers while
* leveraging STX's template processing capabilities.
*
* ## Core Primitives
*
* - `ref()` - Create a reactive reference
* - `reactive()` - Create a reactive object
* - `computed()` - Create a computed value
* - `watch()` - Watch reactive sources
* - `watchEffect()` - Auto-track dependencies
*
* ## Lifecycle Hooks
*
* - `onBeforeMount()` - Before DOM insertion
* - `onMounted()` - Component in DOM
* - `onBeforeUpdate()` - Before re-render
* - `onUpdated()` - After re-render
* - `onBeforeUnmount()` - Before cleanup
* - `onUnmounted()` - After cleanup
*
* ## Usage
*
* ```html
* <script client>
* import { ref, onMounted, watch } from 'stx'
*
* const count = ref(0)
* const users = ref([])
*
* onMounted(async () => {
* users.value = await fetch('/api/users').then(r => r.json())
* })
*
* watch(count, (newVal, oldVal) => {
* console.log(`Count changed: ${oldVal} -> ${newVal}`)
* })
* </script>
*
* <button @click="count++">Count: {{ count }}</button>
* ```
*
* @module reactivity
*/
/** Reactive reference wrapper */
export declare interface Ref<T> {
value: T
subscribe: (callback: (value: T, oldValue: T) => void) => () => void
}
/** Watch options */
export declare interface WatchOptions {
immediate?: boolean
deep?: boolean
flush?: 'pre' | 'post' | 'sync'
}
/** Component instance for tracking lifecycle */
export declare interface ComponentInstance {
isMounted: boolean
isUnmounted: boolean
hooks: {
beforeMount: LifecycleHook[]
mounted: LifecycleHook[]
beforeUpdate: LifecycleHook[]
updated: LifecycleHook[]
beforeUnmount: LifecycleHook[]
unmounted: LifecycleHook[]
}
effects: (() => void)[]
scope: ReactiveScope
}
/** Reactive scope for tracking dependencies */
export declare interface ReactiveScope {
refs: Map<symbol, Ref<unknown>>
effects: Set<() => void>
cleanups: (() => void)[]
}
/** Subscriber callback */
export type WatchCallback<T> = (newValue: T, oldValue: T | undefined) => void
/** Lifecycle hook callback */
export type LifecycleHook = () => void | Promise<void>
export {
ref as createRef,
reactive as createReactive,
computed as createComputed,
};