@stacksjs/stx 0.2.0 → 0.2.3

package/dist/reactive-bindings.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Process reactive bindings in HTML template
+ * Detects {{ $store.value }} patterns in attribute values
+ */
+export declare function processReactiveBindings(html: string): ProcessedBindings;
+/**
+ * Generate the client-side JavaScript for reactive bindings
+ */
+export declare function generateBindingsRuntime(bindings: BindingInfo[], stores: Set<string>): string;
+/**
+ * Process template with reactive bindings and generate runtime
+ */
+export declare function processTemplateBindings(html: string): string;
+declare interface BindingInfo {
+  elementId: string
+  attribute: string
+  expression: string
+  stores: string[]
+}
+declare interface ProcessedBindings {
+  html: string
+  bindings: BindingInfo[]
+  stores: Set<string>
+}

package/dist/reactive.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Process reactive directives in a template.
+ *
+ * Transforms `x-data`, `x-model`, `x-show`, etc. into client-side reactivity.
+ *
+ * @param template - The HTML template string
+ * @param context - Template context
+ * @param filePath - Source file path for error messages
+ * @returns Processed template with reactive runtime script
+ */
+export declare function processReactiveDirectives(template: string, _context: Record<string, unknown>, _filePath: string): string;
+/**
+ * Check if a template contains reactive directives
+ */
+export declare function hasReactiveDirectives(template: string): boolean;
+/**
+ * Reactive Directives Module
+ *
+ * Provides Alpine.js-style reactive state management for STX templates.
+ * Transforms `x-data`, `x-model`, `x-show`, `x-text`, `x-bind` into client-side reactivity.
+ *
+ * ## Supported Syntax
+ *
+ * ### x-data - Define reactive state
+ * ```html
+ * <div x-data="{ count: 0, name: '' }">
+ *   <p x-text="count"></p>
+ *   <button @click="count++">Increment</button>
+ * </div>
+ * ```
+ *
+ * ### x-model - Two-way binding
+ * ```html
+ * <input x-model="name" type="text">
+ * <textarea x-model="message"></textarea>
+ * <select x-model="selected">...</select>
+ * <input x-model="checked" type="checkbox">
+ * ```
+ *
+ * ### x-show / x-hide - Toggle visibility
+ * ```html
+ * <div x-show="isOpen">Visible when isOpen is true</div>
+ * <div x-hide="isLoading">Hidden when isLoading is true</div>
+ * ```
+ *
+ * ### x-text / x-html - Bind content
+ * ```html
+ * <span x-text="message"></span>
+ * <div x-html="htmlContent"></div>
+ * ```
+ *
+ * ### x-bind / :attr - Bind attributes
+ * ```html
+ * <button x-bind:disabled="isLoading">Submit</button>
+ * <div :class="{ active: isActive, hidden: !isVisible }">...</div>
+ * <img :src="imageUrl" :alt="imageAlt">
+ * ```
+ *
+ * ### x-ref - Element references
+ * ```html
+ * <input x-ref="input">
+ * <button @click="$refs.input.focus()">Focus</button>
+ * ```
+ *
+ * ### x-init - Run code on mount
+ * ```html
+ * <div x-data="{ items: [] }" x-init="items = await fetchItems()">
+ * ```
+ *
+ * @module reactive
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface ReactiveScope {
+  id: string
+  selector: string
+  stateExpr: string
+  initExpr: string | null
+  bindings: ReactiveBinding[]
+  refs: Map<string, string>
+}
+export declare interface ReactiveBinding {
+  elementId: string
+  type: 'model' | 'show' | 'hide' | 'text' | 'html' | 'bind' | 'class' | 'style'
+  expression: string
+  attribute?: string
+  inputType?: string
+  transition?: TransitionConfig
+}
+export declare interface TransitionConfig {
+  enabled: boolean
+  enter?: string
+  enterStart?: string
+  enterEnd?: string
+  leave?: string
+  leaveStart?: string
+  leaveEnd?: string
+  duration?: number
+}

package/dist/reactivity.d.ts

@@ -0,0 +1,253 @@
+/**
+ * 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,
+};

package/dist/route-middleware.d.ts

@@ -0,0 +1,232 @@
+import path from 'node:path';
+import type { PageMeta } from './head';
+/**
+ * Redirect to a different route
+ *
+ * @param path - Path to redirect to
+ * @param options - Redirect options
+ * @returns Navigation result for the middleware system
+ *
+ * @example
+ * ```typescript
+ * export default defineMiddleware(async (ctx) => {
+ *   if (!ctx.cookies.get('token')) {
+ *     return navigateTo('/login')
+ *   }
+ * })
+ * ```
+ */
+export declare function navigateTo(path: string, options?: NavigateToOptions): NavigateToResult;
+/**
+ * Abort navigation with an error
+ *
+ * @param error - Error message or error object
+ * @returns Navigation result for the middleware system
+ *
+ * @example
+ * ```typescript
+ * export default defineMiddleware(async (ctx) => {
+ *   if (!hasPermission(ctx)) {
+ *     return abortNavigation({ statusCode: 403, message: 'Forbidden' })
+ *   }
+ * })
+ * ```
+ */
+export declare function abortNavigation(error: string | NavigationError): AbortNavigationResult;
+/**
+ * Define a route middleware
+ *
+ * @param handler - Middleware handler function
+ * @param options - Middleware options
+ * @returns Middleware definition
+ *
+ * @example
+ * ```typescript
+ * // middleware/auth.ts - runs on both server and client
+ * export default defineMiddleware(async (ctx) => {
+ *   const token = ctx.cookies.get('auth_token')
+ *   if (!token) {
+ *     return navigateTo('/login')
+ *   }
+ * })
+ *
+ * // middleware/theme.ts - client only (can use localStorage)
+ * export default defineMiddleware(async (ctx) => {
+ *   const theme = ctx.storage.get('theme')
+ *   ctx.state.theme = theme || 'light'
+ * }, { mode: 'client' })
+ * ```
+ */
+export declare function defineMiddleware(handler: RouteMiddlewareHandler, options?: MiddlewareOptions): RouteMiddlewareDefinition;
+/**
+ * Create a cookie manager for server-side usage
+ */
+export declare function createServerCookieManager(request: Request, responseHeaders: Headers): CookieManager;
+/**
+ * Create a cookie manager for client-side usage
+ */
+export declare function createClientCookieManager(): CookieManager;
+/**
+ * Create a storage manager (localStorage wrapper)
+ */
+export declare function createStorageManager(): StorageManager;
+/**
+ * Register a middleware by name
+ */
+export declare function registerMiddleware(name: string, middleware: RouteMiddlewareDefinition): void;
+/**
+ * Get a middleware by name
+ */
+export declare function getMiddleware(name: string): RouteMiddlewareDefinition | undefined;
+/**
+ * Check if a middleware is registered
+ */
+export declare function hasMiddleware(name: string): boolean;
+/**
+ * Clear all registered middleware
+ */
+export declare function clearMiddleware(): void;
+/**
+ * Get all registered middleware names
+ */
+export declare function getMiddlewareNames(): string[];
+/**
+ * Load middleware from the middleware/ directory
+ */
+export declare function loadMiddlewareFromDirectory(baseDir: string, middlewareDir?: string): Promise<void>;
+/**
+ * Create a route location object
+ */
+export declare function createRouteLocation(pathname: string, params: Record<string, string>, meta: PageMeta, search?: string): RouteLocation;
+/**
+ * Create a middleware context
+ */
+export declare function createMiddlewareContext(to: RouteLocation, from: RouteLocation | null, request?: Request): MiddlewareContext;
+/**
+ * Run middleware chain for a route
+ *
+ * @param middlewareNames - Names of middleware to run
+ * @param context - Middleware context
+ * @returns Result of middleware execution
+ */
+export declare function runMiddleware(middlewareNames: string | string[], context: MiddlewareContext): Promise<MiddlewareResult>;
+/**
+ * Route location information
+ */
+export declare interface RouteLocation {
+  path: string
+  params: Record<string, string>
+  query: Record<string, string>
+  fullPath: string
+  meta: PageMeta
+}
+/**
+ * Cookie manager for reading/writing cookies
+ */
+export declare interface CookieManager {
+  get(name: string): string | undefined
+  set(name: string, value: string, options?: CookieOptions): void
+  delete(name: string): void
+  getAll(): Record<string, string>
+}
+/**
+ * Cookie options for setting cookies
+ */
+export declare interface CookieOptions {
+  expires?: Date | number
+  path?: string
+  domain?: string
+  secure?: boolean
+  httpOnly?: boolean
+  sameSite?: 'strict' | 'lax' | 'none'
+}
+/**
+ * Safe localStorage wrapper (returns null on server)
+ */
+export declare interface StorageManager {
+  get(key: string): string | null
+  set(key: string, value: string): void
+  remove(key: string): void
+  isAvailable(): boolean
+}
+/**
+ * Middleware context passed to handlers
+ */
+export declare interface MiddlewareContext {
+  to: RouteLocation
+  from: RouteLocation | null
+  isClient: boolean
+  isServer: boolean
+  cookies: CookieManager
+  storage: StorageManager
+  state: Record<string, unknown>
+  request?: Request
+  responseHeaders: Headers
+}
+/**
+ * Middleware definition options
+ */
+export declare interface MiddlewareOptions {
+  mode?: MiddlewareMode
+}
+/**
+ * Registered middleware definition
+ */
+export declare interface RouteMiddlewareDefinition {
+  handler: RouteMiddlewareHandler
+  mode: MiddlewareMode
+}
+/**
+ * Navigation redirect result
+ */
+export declare interface NavigateToResult {
+  type: 'redirect'
+  path: string
+  options: NavigateToOptions
+}
+/**
+ * Navigation abort result
+ */
+export declare interface AbortNavigationResult {
+  type: 'abort'
+  error: NavigationError
+}
+/**
+ * Options for navigateTo()
+ */
+export declare interface NavigateToOptions {
+  replace?: boolean
+  external?: boolean
+  redirectCode?: 301 | 302 | 303 | 307 | 308
+}
+/**
+ * Navigation error for abortNavigation()
+ */
+export declare interface NavigationError {
+  statusCode: number
+  message: string
+}
+/**
+ * Result of running middleware chain
+ */
+export declare interface MiddlewareResult {
+  passed: boolean
+  redirect?: NavigateToResult
+  abort?: AbortNavigationResult
+  state: Record<string, unknown>
+  responseHeaders: Headers
+}
+/**
+ * Middleware execution mode
+ */
+export type MiddlewareMode = 'universal' | 'server' | 'client'
+/**
+ * Middleware handler function
+ */
+export type RouteMiddlewareHandler = (
+  context: MiddlewareContext
+) => void | Promise<void> | NavigationResult | Promise<NavigationResult | void>
+/**
+ * Result from middleware (redirect or abort)
+ */
+export type NavigationResult = NavigateToResult | AbortNavigationResult

package/dist/router.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Creates a router from a pages directory
+ */
+export declare function createRouter(baseDir: string, options?: RouterOptions): Route[];
+/**
+ * Matches a URL pathname against routes
+ */
+export declare function matchRoute(pathname: string, routes: Route[]): RouteMatch | null;
+/**
+ * Gets route params from a URL
+ */
+export declare function getRouteParams(pathname: string, routes: Route[]): Record<string, string> | null;
+/**
+ * Pretty prints routes for console output
+ */
+export declare function formatRoutes(routes: Route[], baseDir: string): string[];
+export declare interface Route {
+  pattern: string
+  regex: RegExp
+  params: string[]
+  filePath: string
+  isDynamic: boolean
+}
+export declare interface RouteMatch {
+  route: Route
+  params: Record<string, string>
+}
+export declare interface RouterOptions {
+  pagesDir?: string
+  extensions?: string[]
+}

package/dist/routes.d.ts

@@ -22,13 +22,6 @@ export declare function processRouteDirectives(template: string): string;
  * Reset all routes (mainly for testing)
  */
 export declare function resetRoutes(): void;
-/**
- * Laravel-like named routes system for stx
- *
- * This provides the ability to define routes with names and generate URLs for them,
- * similar to Laravel's route naming and the route() helper.
- */
-/* eslint-disable no-new-func */
 declare interface RouteDefinition {
   path: string
   name?: string