@stacksjs/stx/dist/composition-api.d.ts

A performant UI Framework. Powered by Bun.

/**
 * Generate a unique scope ID.
 */
export declare function generateScopeId(): string;
/**
 * Create a new component instance.
 */
export declare function createComponentInstance(parent?: StxComponentInstance | null): StxComponentInstance;
/**
 * Set the current component instance for setup execution.
 * @internal
 */
export declare function setCurrentInstance(instance: StxComponentInstance | null): void;
/**
 * Get the current component instance.
 * Must be called during component setup (inside <script> block).
 *
 * ```ts
 * const instance = getCurrentInstance()
 * console.log(instance?.props)
 * ```
 */
export declare function getCurrentInstance(): StxComponentInstance | null;
/**
 * Reset all component instance state.
 * @internal - Used for testing to clear global state between tests.
 */
export declare function resetComponentState(): void;
/**
 * Provide a value for injection into descendant components.
 *
 * ```ts
 * // Parent component
 * provide('theme', 'dark')
 * provide('user', { name: 'Alice' })
 * ```
 *
 * @param key - Injection key (string or symbol)
 * @param value - The value to provide
 */
export declare function provide<T>(key: string | symbol, value: T): void;
/**
 * Inject a value provided by an ancestor component.
 *
 * ```ts
 * // Child component
 * const theme = inject('theme', 'light') // 'dark' if provided, 'light' as fallback
 * const user = inject<{ name: string }>('user')
 * ```
 *
 * @param key - Injection key to look up
 * @param defaultValue - Fallback value if not provided by any ancestor
 * @returns The injected value, or defaultValue if not found
 */
export declare function inject<T>(key: string | symbol, defaultValue?: T): T | undefined;
/**
 * Set a global provide value (used by createApp().provide()).
 * @internal
 */
export declare function setGlobalProvide<T>(key: string | symbol, value: T): void;
/**
 * Define the events a component can emit.
 * Returns a typed emit function.
 *
 * ```ts
 * const emit = defineEmits<{
 *   change: [value: string]
 *   'update:modelValue': [value: any]
 * }>()
 *
 * // Or with string array
 * const emit = defineEmits(['change', 'update:modelValue'])
 *
 * emit('change', 'newValue')
 * ```
 */
export declare function defineEmits<T extends Record<string, any[]> = Record<string, any[]>>(_events?: string[] | T): EmitFn<Extract<keyof T, string>>;
/**
 * Expose public properties from a component instance.
 * These properties become accessible via template refs from the parent.
 *
 * ```ts
 * const count = ref(0)
 * const increment = () => count.value++
 *
 * defineExpose({ count, increment })
 * ```
 *
 * @param exposed - Object of properties to expose
 */
export declare function defineExpose(exposed: Record<string, unknown>): void;
/**
 * Wait for the next DOM update cycle.
 *
 * ```ts
 * await nextTick()
 * // DOM is now updated
 *
 * // Or with callback:
 * nextTick(() => {
 *   // DOM is now updated
 * })
 * ```
 *
 * @param fn - Optional callback to run after the tick
 * @returns Promise that resolves after the next microtask
 */
export declare function nextTick(fn?: () => void): Promise<void>;
/**
 * Register an error captured hook.
 * Called when an error is captured from a descendant component.
 *
 * ```ts
 * onErrorCaptured((error, instance, info) => {
 *   console.error('Caught error:', error, info)
 *   return false // prevents further propagation
 * })
 * ```
 *
 * @param hook - Error handler function. Return false to stop propagation.
 */
export declare function onErrorCaptured(hook: (error: Error, instance: StxComponentInstance | null, info: string) => boolean | void): void;
/**
 * Propagate an error up the component tree.
 * Calls onErrorCaptured hooks on each ancestor.
 * @internal
 */
export declare function handleError(error: Error, instance: StxComponentInstance | null, info: string): void;
/**
 * Get the current component's slots.
 *
 * ```ts
 * const slots = useSlots()
 * if (slots.header) {
 *   // render header slot
 * }
 * ```
 */
export declare function useSlots(): Record<string, any>;
/**
 * Get the current component's non-prop attributes.
 *
 * ```ts
 * const attrs = useAttrs()
 * // attrs contains all attributes not declared as props
 * ```
 */
export declare function useAttrs(): Record<string, unknown>;
/**
 * Integrate provide/inject with the server-side template context.
 * Called during component rendering in process.ts.
 * @internal
 */
export declare function createProvideContext(parentContext: Record<string, any>): Record<string, any>;
/**
 * Generate the client-side runtime code for the Composition API.
 * This is injected into the page's runtime script.
 * @internal
 */
export declare function generateCompositionRuntime(): string;
/**
 * STX Composition API
 *
 * Provides Vue-compatible Composition API features:
 * - provide() / inject() for dependency injection across components
 * - defineEmits() for typed event emission
 * - defineExpose() for exposing component internals to template refs
 * - nextTick() for waiting on DOM updates
 * - getCurrentInstance() for accessing the current component instance
 * - onErrorCaptured() for error boundary handling
 *
 * @module composition-api
 */
/** Represents a component instance in the stx component tree */
export declare interface StxComponentInstance {
  scopeId: string
  parent: StxComponentInstance | null
  provides: Map<string | symbol, unknown>
  exposed: Record<string, unknown> | null
  refs: Record<string, Element | null>
  props: Record<string, unknown>
  attrs: Record<string, unknown>
  slots: Record<string, any>
  emit: EmitFn
  el: Element | null
  errorCapturedHooks: Array<(error: Error, instance: StxComponentInstance | null, info: string) => boolean | void>
  isMounted: boolean
}
/** Type-safe emit function */
export type EmitFn<T extends string = string> = (event: T, ...args: any[]) => void