@stacksjs/stx 0.2.0 → 0.2.3

package/dist/composables.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Create a new component instance context.
+ * Called internally when a component script starts executing.
+ */
+export declare function createComponentInstance(element?: Element): ComponentInstance;
+/**
+ * Set the current component instance context.
+ */
+export declare function setCurrentInstance(instance: ComponentInstance | null): void;
+/**
+ * Get the current component instance context.
+ */
+export declare function getCurrentInstance(): ComponentInstance | null;
+/**
+ * Register a callback to run when the component is mounted to the DOM.
+ *
+ * @example
+ * ```html
+ * <script client>
+ * import { onMount } from 'stx'
+ *
+ * onMount(() => {
+ *   console.log('Component mounted!')
+ *
+ *   // Return cleanup function (optional)
+ *   return () => {
+ *     console.log('Cleanup on unmount')
+ *   }
+ * })
+ * </script>
+ * ```
+ */
+export declare function onMount(hook: LifecycleHook): void;
+/**
+ * Register a callback to run when the component is destroyed/unmounted.
+ *
+ * @example
+ * ```html
+ * <script client>
+ * import { onMount, onDestroy } from 'stx'
+ *
+ * onMount(() => {
+ *   const interval = setInterval(() => console.log('tick'), 1000)
+ *
+ *   onDestroy(() => {
+ *     clearInterval(interval)
+ *   })
+ * })
+ * </script>
+ * ```
+ */
+export declare function onDestroy(hook: CleanupFn): void;
+/**
+ * Register a callback to run when the component updates.
+ *
+ * @example
+ * ```html
+ * <script client>
+ * import { onUpdate } from 'stx'
+ *
+ * onUpdate(() => {
+ *   console.log('Component updated!')
+ * })
+ * </script>
+ * ```
+ */
+export declare function onUpdate(hook: LifecycleHook): void;
+/**
+ * Create a ref for holding a DOM element reference.
+ *
+ * @example
+ * ```html
+ * <script client>
+ * import { ref, onMount } from 'stx'
+ *
+ * const inputRef = ref<HTMLInputElement>()
+ *
+ * onMount(() => {
+ *   inputRef.value?.focus()
+ * })
+ * </script>
+ *
+ * <input type="text" @ref="inputRef" />
+ * ```
+ */
+export declare function ref<T = HTMLElement>(initialValue?: T | null): Ref<T>;
+/**
+ * Create a named ref that can be bound via @ref="name" in templates.
+ */
+export declare function namedRef<T = HTMLElement>(name: string, initialValue?: T | null): Ref<T>;
+/**
+ * Watch a reactive source and run a callback when it changes.
+ *
+ * @example
+ * ```html
+ * <script client>
+ * import { watch } from 'stx'
+ * import { counterStore } from '@stores'
+ *
+ * watch(
+ *   () => counterStore.count,
+ *   (newVal, oldVal) => {
+ *     console.log(`Count changed: ${oldVal} → ${newVal}`)
+ *   }
+ * )
+ * </script>
+ * ```
+ */
+export declare function watch<T>(source: WatchSource<T>, callback: WatchCallback<T>, options?: { immediate?: boolean }): () => void;
+/**
+ * Create a computed value that updates when dependencies change.
+ *
+ * @example
+ * ```html
+ * <script client>
+ * import { computed } from 'stx'
+ * import { counterStore } from '@stores'
+ *
+ * const doubleCount = computed(() => counterStore.count * 2)
+ *
+ * // Access value
+ * console.log(doubleCount.value)
+ * </script>
+ * ```
+ */
+export declare function computed<T>(getter: () => T): { readonly value: T };
+/**
+ * Initialize a component and run its setup.
+ * This is called by the STX runtime when a component is created.
+ */
+export declare function setupComponent(element: Element, setup: () => void): ComponentInstance;
+/**
+ * Mount a component instance - runs onMount hooks.
+ */
+export declare function mountComponent(instance: ComponentInstance): void;
+/**
+ * Update a component instance - runs onUpdate hooks.
+ */
+export declare function updateComponent(instance: ComponentInstance): void;
+/**
+ * Destroy a component instance - runs cleanup and onDestroy hooks.
+ */
+export declare function destroyComponent(instance: ComponentInstance): void;
+/**
+ * Generate the client-side runtime script for lifecycle management.
+ */
+export declare function generateLifecycleRuntime(): string;
+/**
+ * Create a typed injection key.
+ *
+ * @example
+ * ```typescript
+ * const ThemeKey = createInjectionKey<{ mode: 'dark' | 'light' }>('theme')
+ * ```
+ */
+export declare function createInjectionKey<T>(description?: string): InjectionKey<T>;
+/**
+ * Provide a value that can be injected by descendant components.
+ *
+ * @example
+ * ```html
+ * <script server>
+ * import { provide } from 'stx'
+ *
+ * // Provide a theme object
+ * provide('theme', { mode: 'dark', accent: 'purple' })
+ *
+ * // Or with a typed key
+ * import { ThemeKey } from './injection-keys'
+ * provide(ThemeKey, { mode: 'dark', accent: 'purple' })
+ * </script>
+ * ```
+ */
+export declare function provide<T>(key: string | InjectionKey<T>, value: T): void;
+/**
+ * Inject a value provided by an ancestor component.
+ *
+ * @example
+ * ```html
+ * <script client>
+ * import { inject } from 'stx'
+ *
+ * // Inject with default value
+ * const theme = inject('theme', { mode: 'light', accent: 'blue' })
+ *
+ * // Inject required value (throws if not provided)
+ * const auth = inject('auth')
+ * </script>
+ * ```
+ */
+export declare function inject<T>(key: string | InjectionKey<T>): T | undefined;
+export declare function inject<T>(key: string | InjectionKey<T>, defaultValue: T): T;
+export declare function inject<T>(key: string | InjectionKey<T>, defaultValue?: T): T | undefined;
+/**
+ * Create a new injection scope.
+ * Called internally when entering a component.
+ */
+export declare function pushInjectionScope(): void;
+/**
+ * Exit the current injection scope.
+ * Called internally when leaving a component.
+ */
+export declare function popInjectionScope(): void;
+/**
+ * Run a function within a new injection scope.
+ * Useful for component rendering.
+ */
+export declare function withInjectionScope<T>(fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Clear all injections (for testing).
+ */
+export declare function clearInjections(): void;
+/**
+ * Alias for onMount - matches common naming conventions.
+ */
+export declare const onMounted: unknown;
+/**
+ * Alias for onDestroy - matches Vue naming.
+ */
+export declare const onUnmounted: unknown;
+/**
+ * Alias for onUpdate - matches Vue naming.
+ */
+export declare const onUpdated: unknown;
+/** Built-in injection key for theme */
+export declare const ThemeKey: unknown;
+/** Built-in injection key for router */
+export declare const RouterKey: (createInjectionKey<{
+  currentRoute: string
+  navigate: (path: string)) => unknown;
+/** Built-in injection key for i18n */
+export declare const I18nKey: (createInjectionKey<{
+  locale: string
+  t: (key: string)) => unknown;
+export declare interface Ref<T> {
+  value: T | null
+  current: T | null
+}
+export declare interface ComponentInstance {
+  id: string
+  element: Element | null
+  mountHooks: LifecycleHook[]
+  destroyHooks: CleanupFn[]
+  updateHooks: LifecycleHook[]
+  refs: Map<string, Ref<any>>
+  watchers: Array<{ stop: () => void }>
+  isMounted: boolean
+}
+/**
+ * STX Composables
+ *
+ * Vue-inspired composable utilities for STX components:
+ * - Lifecycle hooks (onMount, onDestroy, onUpdate)
+ * - Refs for DOM element references
+ * - Watch and computed for reactivity
+ *
+ * @module composables
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export type LifecycleHook = () => void | (() => void)
+export type CleanupFn = () => void
+export type WatchCallback<T> = (newValue: T, oldValue: T | undefined) => void | CleanupFn
+export type WatchSource<T> = () => T
+/** Symbol for injection keys */
+export type InjectionKey<T> = symbol & { __type?: T }
+export { ref as createRef };

package/dist/composition-api.d.ts

@@ -0,0 +1,190 @@
+/**
+ * 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

package/dist/computed.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Create a reactive reference
+ */
+export declare function ref<T>(initialValue: T): Ref<T>;
+/**
+ * Check if a value is a ref
+ */
+export declare function isRef<T>(value: unknown): value is Ref<T>;
+/**
+ * Unwrap a ref to get its value
+ */
+export declare function unref<T>(value: T | Ref<T>): T;
+/**
+ * Convert all properties of an object to refs
+ */
+export declare function toRefs<T extends object>(obj: T): { [K in keyof T]: Ref<T[K]> };
+/**
+ * Create a shallow reactive object
+ */
+export declare function shallowRef<T>(initialValue: T): Ref<T>;
+/**
+ * Create a computed property with automatic dependency tracking
+ */
+export declare function computed<T>(getter: () => T): ComputedRef<T>;
+export declare function computed<T>(options: ComputedOptions<T>): WritableComputedRef<T>;
+export declare function computed<T>(getterOrOptions: (() => T) | ComputedOptions<T>): ComputedRef<T> | WritableComputedRef<T>;
+/**
+ * Watch a reactive source and run a callback when it changes
+ */
+export declare function watch<T>(source: Ref<T> | (() => T), callback: (newValue: T, oldValue: T | undefined) => void, options?: WatchOptions): WatchStopHandle;
+/**
+ * Watch multiple sources
+ */
+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 | undefined : never }
+  ) => void, options?: WatchOptions): WatchStopHandle;
+/**
+ * Watch and run effect immediately, auto-tracking dependencies
+ */
+export declare function watchEffect(effect: () => void | (() => void), options?: Pick<WatchOptions, 'flush'>): WatchStopHandle;
+/**
+ * Process @computed directives in templates
+ */
+export declare function processComputedDirectives(template: string, context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Process @watch directives in templates
+ */
+export declare function processWatchDirectives(template: string, _context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Create a debounced computed
+ */
+export declare function debouncedComputed<T>(getter: () => T, delay?: number): ComputedRef<T>;
+/**
+ * Create a throttled computed
+ */
+export declare function throttledComputed<T>(getter: () => T, limit?: number): ComputedRef<T>;
+/**
+ * Computed Properties Module
+ *
+ * Provides reactive computed values with automatic dependency tracking.
+ * Computed properties automatically update when their dependencies change,
+ * and are cached until dependencies are modified.
+ *
+ * @example
+ * ```typescript
+ * const firstName = ref('John')
+ * const lastName = ref('Doe')
+ *
+ * const fullName = computed(() => `${firstName.value} ${lastName.value}`)
+ *
+ * console.log(fullName.value) // 'John Doe'
+ * firstName.value = 'Jane'
+ * console.log(fullName.value) // 'Jane Doe'
+ * ```
+ */
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface Ref<T> {
+  value: T
+  subscribe: (callback: (value: T) => void) => () => void
+  peek: () => T
+}
+export declare interface ComputedRef<T> extends Ref<T> {
+  invalidate: () => void
+  dirty: boolean
+  deps: Set<Ref<unknown>>
+}
+export declare interface WritableComputedRef<T> extends ComputedRef<T> {
+  value: T
+}
+export declare interface ComputedOptions<T> {
+  get: () => T
+  set?: (value: T) => void
+  lazy?: boolean
+  equals?: (a: T, b: T) => boolean
+}
+export declare interface WatchOptions {
+  immediate?: boolean
+  deep?: boolean
+  flush?: 'pre' | 'post' | 'sync'
+  once?: boolean
+}
+export declare interface WatchStopHandle {
+  (): void
+  pause: () => void
+  resume: () => void
+}
+export {
+  ref as stxRef,
+  computed as stxComputed,
+  watch as stxWatch,
+  watchMultiple as stxWatchMultiple,
+  watchEffect as stxWatchEffect,
+  isRef as stxIsRef,
+  unref as stxUnref,
+  toRefs as stxToRefs,
+  shallowRef as stxShallowRef,
+  debouncedComputed as stxDebouncedComputed,
+  throttledComputed as stxThrottledComputed,
+};
+export default {
+  ref,
+  computed,
+  watch,
+  watchMultiple,
+  watchEffect,
+  isRef,
+  unref,
+  toRefs,
+  shallowRef,
+  debouncedComputed,
+  throttledComputed,
+  processComputedDirectives,
+  processWatchDirectives,
+};

package/dist/conditionals.d.ts

@@ -1,19 +1,31 @@
 /**
  * Process switch statements (@switch, @case, @default)
+ *
+ * Uses the parser module for proper handling of:
+ * - Nested parentheses in expressions (e.g., @switch(fn(a, fn(b))))
+ * - Nested @switch blocks
+ * - @break directives
  */
-export declare function processSwitchStatements(template: string, context: Record<string, any>, filePath: string): string;
+export declare function processSwitchStatements(template: string, context: Record<string, any>, _filePath: string): string;
 /**
  * Process conditionals (@if, @elseif, @else, @unless)
+ *
+ * Uses the parser module for proper handling of:
+ * - Nested parentheses in conditions (e.g., @if(fn(a, fn(b))))
+ * - Nested @if blocks
+ * - Multiple @elseif branches
  */
 export declare function processConditionals(template: string, context: Record<string, any>, filePath: string): string;
 /**
  * Process @auth and permissions directives
+ *
+ * @see Authentication Directive Documentation above for required context shapes
  */
 export declare function processAuthDirectives(template: string, context: Record<string, any>): string;
 /**
  * Process @isset and @empty directives
  */
-export declare function processIssetEmptyDirectives(template: string, context: Record<string, any>, filePath?: string): string;
+export declare function processIssetEmptyDirectives(template: string, context: Record<string, any>, _filePath?: string): string;
 /**
  * Process @env directive to conditionally render content based on environment
  */

package/dist/config.d.ts

@@ -1,8 +1,41 @@
 import type { StxConfig, StxOptions } from './types';
+export declare function loadStxConfig(): Promise<StxConfig>;
 /**
  * Helper function to define stx configuration
  */
 export declare function defineStxConfig(config: StxOptions): StxOptions;
+/**
+ * Validate stx configuration
+ *
+ * @param config - Configuration to validate
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validateConfig(myConfig)
+ * if (!result.valid) {
+ *   console.error('Config errors:', result.errors)
+ * }
+ * ```
+ */
+export declare function validateConfig(config: StxOptions): ConfigValidationResult;
 export declare const defaultConfig: StxConfig;
-// eslint-disable-next-line antfu/no-top-level-await
-export declare const config: StxConfig;
+// Export a synchronous getter that returns defaults immediately, then loads async
+// This allows the module to be imported instantly without blocking
+export declare const config: StxConfig;
+/**
+ * Configuration validation error
+ */
+export declare interface ConfigValidationError {
+  path: string
+  message: string
+  severity: 'error' | 'warning'
+}
+/**
+ * Configuration validation result
+ */
+export declare interface ConfigValidationResult {
+  valid: boolean
+  errors: ConfigValidationError[]
+  warnings: ConfigValidationError[]
+}