@stacksjs/stx 0.2.0 → 0.2.3

package/dist/async-components.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Process @async directives in templates.
+ *
+ * Syntax:
+ *   @async(component: 'ComponentName', timeout: 5000)
+ *     <loading content>
+ *   @error
+ *     <error content>
+ *   @endasync
+ */
+export declare function processAsyncDirectives(template: string, _context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Define an async component.
+ */
+export declare function defineAsyncComponent(options: DefineAsyncComponentOptions | (() => Promise<{ default: string } | string>)): AsyncComponentDefinition;
+/**
+ * Check if a value is an async component definition.
+ */
+export declare function isAsyncComponent(value: unknown): value is AsyncComponentDefinition;
+/**
+ * Generate CSS for async component styling.
+ */
+export declare function generateAsyncComponentCSS(): string;
+/**
+ * Generate client-side runtime for async components.
+ */
+export declare function generateAsyncComponentRuntime(): string;
+/**
+ * STX Async Components
+ *
+ * Provides lazy loading capabilities for components with loading and error states.
+ *
+ * @module async-components
+ *
+ * @example
+ * ```html
+ * @async(component: 'HeavyChart', timeout: 5000)
+ *   <div class="loading">Loading chart...</div>
+ * @error
+ *   <div class="error">Failed to load chart</div>
+ * @endasync
+ * ```
+ *
+ * Or inline:
+ * ```html
+ * <AsyncComponent
+ *   :component="() => import('./HeavyChart.stx')"
+ *   :timeout="5000"
+ * >
+ *   <template #loading>Loading...</template>
+ *   <template #error="{ error }">Error: {{ error.message }}</template>
+ * </AsyncComponent>
+ * ```
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface AsyncComponentOptions {
+  component: string
+  timeout?: number
+  delay?: number
+  suspensible?: boolean
+  loadingComponent?: string
+  errorComponent?: string
+  retries?: number
+  props?: Record<string, unknown>
+}
+export declare interface AsyncComponentState {
+  status: 'pending' | 'loading' | 'resolved' | 'rejected'
+  component: string | null
+  error: Error | null
+  attempts: number
+}
+/**
+ * Define an async component for programmatic use.
+ *
+ * @example
+ * ```typescript
+ * const AsyncChart = defineAsyncComponent({
+ *   loader: () => import('./Chart.stx'),
+ *   loadingComponent: LoadingSpinner,
+ *   errorComponent: ErrorDisplay,
+ *   delay: 200,
+ *   timeout: 3000
+ * })
+ * ```
+ */
+export declare interface DefineAsyncComponentOptions {
+  loader: () => Promise<{ default: string } | string>
+  loadingComponent?: string
+  errorComponent?: string
+  delay?: number
+  timeout?: number
+  suspensible?: boolean
+  onLoadStart?: () => void
+  onLoadEnd?: () => void
+  onError?: (error: Error, retry: () => void, fail: () => void, attempts: number) => void
+}
+export declare interface AsyncComponentDefinition extends DefineAsyncComponentOptions {
+  __asyncComponent: true
+}

package/dist/auth.d.ts

@@ -1,9 +1,7 @@
-/**
- * Module for handling authentication and authorization in templates
- */
 /**
  * Safely evaluates an auth expression within the given context
  * Similar to evaluateExpression but specialized for auth conditionals
+ * Uses the safe evaluator to prevent code injection
  *
  * @param {string} expression - The expression to evaluate
  * @param {Record<string, any>} context - The context object containing variables

package/dist/browser-composables.d.ts

@@ -0,0 +1,314 @@
+/**
+ * Reactive localStorage with automatic serialization.
+ *
+ * @example
+ * ```typescript
+ * const theme = useLocalStorage('theme', 'dark')
+ * console.log(theme.value) // 'dark'
+ * theme.value = 'light' // automatically saved
+ * ```
+ */
+export declare function useLocalStorage<T>(key: string, defaultValue: T): { value: T; remove: () => void };
+/**
+ * Reactive sessionStorage with automatic serialization.
+ *
+ * @example
+ * ```typescript
+ * const token = useSessionStorage('auth_token', null)
+ * ```
+ */
+export declare function useSessionStorage<T>(key: string, defaultValue: T): { value: T; remove: () => void };
+/**
+ * Add an event listener with automatic cleanup.
+ *
+ * @example
+ * ```typescript
+ * useEventListener('resize', () => console.log('resized'))
+ * useEventListener(buttonRef, 'click', () => console.log('clicked'))
+ * ```
+ */
+export declare function useEventListener<K extends keyof WindowEventMap>(event: K, handler: (e: WindowEventMap[K]) => void, options?: AddEventListenerOptions): () => void;
+export declare function useEventListener<K extends keyof DocumentEventMap>(target: Document, event: K, handler: (e: DocumentEventMap[K]) => void, options?: AddEventListenerOptions): () => void;
+export declare function useEventListener<K extends keyof HTMLElementEventMap>(target: MaybeRef<HTMLElement | null>, event: K, handler: (e: HTMLElementEventMap[K]) => void, options?: AddEventListenerOptions): () => void;
+export declare function useEventListener(...args: any[]): () => void;
+/**
+ * Detect clicks outside an element.
+ *
+ * @example
+ * ```typescript
+ * const dropdownRef = ref<HTMLElement>()
+ * useClickOutside(dropdownRef, () => {
+ *   isOpen.value = false
+ * })
+ * ```
+ */
+export declare function useClickOutside(target: MaybeRef<HTMLElement | null>, handler: (event: MouseEvent) => void): () => void;
+/**
+ * Reactive window size.
+ *
+ * @example
+ * ```typescript
+ * const { width, height } = useWindowSize()
+ * console.log(`${width.value}x${height.value}`)
+ * ```
+ */
+export declare function useWindowSize(): {
+  width: { readonly value: number }
+  height: { readonly value: number }
+};
+/**
+ * Reactive media query.
+ *
+ * @example
+ * ```typescript
+ * const isMobile = useMediaQuery('(max-width: 768px)')
+ * const prefersDark = useMediaQuery('(prefers-color-scheme: dark)')
+ * ```
+ */
+export declare function useMediaQuery(query: string): { readonly value: boolean };
+/**
+ * Common breakpoint helpers.
+ *
+ * @example
+ * ```typescript
+ * const { isMobile, isTablet, isDesktop } = useBreakpoints()
+ * ```
+ */
+export declare function useBreakpoints(): void;
+/**
+ * Detect dark mode preference.
+ *
+ * @example
+ * ```typescript
+ * const isDark = usePrefersDark()
+ * ```
+ */
+export declare function usePrefersDark(): { readonly value: boolean };
+/**
+ * Reactive online/offline status.
+ *
+ * @example
+ * ```typescript
+ * const isOnline = useOnline()
+ * if (!isOnline.value) showOfflineWarning()
+ * ```
+ */
+export declare function useOnline(): { readonly value: boolean };
+/**
+ * Reactive mouse position.
+ *
+ * @example
+ * ```typescript
+ * const { x, y } = useMouse()
+ * ```
+ */
+export declare function useMouse(): {
+  x: { readonly value: number }
+  y: { readonly value: number }
+};
+/**
+ * Reactive scroll position.
+ *
+ * @example
+ * ```typescript
+ * const { x, y } = useScroll()
+ * // Or for a specific element
+ * const { x, y } = useScroll(containerRef)
+ * ```
+ */
+export declare function useScroll(target?: MaybeRef<HTMLElement | null>): {
+  x: { readonly value: number }
+  y: { readonly value: number }
+  isScrolling: { readonly value: boolean }
+};
+/**
+ * Debounce a function.
+ *
+ * @example
+ * ```typescript
+ * const debouncedSearch = useDebounce((query: string) => {
+ *   fetchResults(query)
+ * }, 300)
+ * ```
+ */
+export declare function useDebounce<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Debounce a value.
+ *
+ * @example
+ * ```typescript
+ * const searchQuery = ref('')
+ * const debouncedQuery = useDebouncedValue(() => searchQuery.value, 300)
+ * ```
+ */
+export declare function useDebouncedValue<T>(getter: () => T, delay: number): { readonly value: T };
+/**
+ * Throttle a function.
+ *
+ * @example
+ * ```typescript
+ * const throttledScroll = useThrottle(() => {
+ *   updateHeader()
+ * }, 100)
+ * ```
+ */
+export declare function useThrottle<T extends (...args: any[]) => any>(fn: T, limit: number): (...args: Parameters<T>) => void;
+/**
+ * Reactive interval.
+ *
+ * @example
+ * ```typescript
+ * const { counter, pause, resume, reset } = useInterval(1000)
+ * ```
+ */
+export declare function useInterval(interval: number, options?: { immediate?: boolean }): {
+  counter: { readonly value: number }
+  pause: () => void
+  resume: () => void
+  reset: () => void
+};
+/**
+ * One-time timeout with controls.
+ *
+ * @example
+ * ```typescript
+ * const { isPending, start, stop } = useTimeout(() => {
+ *   showNotification()
+ * }, 5000)
+ * ```
+ */
+export declare function useTimeout(callback: () => void, delay: number): {
+  isPending: { readonly value: boolean }
+  start: () => void
+  stop: () => void
+};
+/**
+ * Boolean toggle.
+ *
+ * @example
+ * ```typescript
+ * const [isOpen, toggle, setOpen] = useToggle(false)
+ * toggle() // true
+ * setOpen(false) // false
+ * ```
+ */
+export declare function useToggle(initial?: any): [{ value: boolean }, () => void, (value: boolean) => void];
+/**
+ * Counter with controls.
+ *
+ * @example
+ * ```typescript
+ * const { count, inc, dec, set, reset } = useCounter(0)
+ * inc() // 1
+ * inc(5) // 6
+ * dec() // 5
+ * ```
+ */
+export declare function useCounter(initial?: any, options?: { min?: number; max?: number }): {
+  count: { value: number }
+  inc: (delta?: number) => void
+  dec: (delta?: number) => void
+  set: (value: number) => void
+  reset: () => void
+};
+/**
+ * Clipboard access.
+ *
+ * @example
+ * ```typescript
+ * const { copy, copied, text } = useClipboard()
+ * await copy('Hello!')
+ * if (copied.value) showToast('Copied!')
+ * ```
+ */
+export declare function useClipboard(): {
+  text: { readonly value: string }
+  copied: { readonly value: boolean }
+  copy: (text: string) => Promise<void>
+  read: () => Promise<string>
+};
+/**
+ * Document title.
+ *
+ * @example
+ * ```typescript
+ * const title = useTitle('My App')
+ * title.value = 'New Page - My App'
+ * ```
+ */
+export declare function useTitle(initial?: string): { value: string };
+/**
+ * Element visibility with IntersectionObserver.
+ *
+ * @example
+ * ```typescript
+ * const target = ref<HTMLElement>()
+ * const { isVisible } = useIntersectionObserver(target)
+ * ```
+ */
+export declare function useIntersectionObserver(target: MaybeRef<HTMLElement | null>, options?: IntersectionObserverInit): {
+  isVisible: { readonly value: boolean }
+  stop: () => void
+};
+/**
+ * Focus state of an element.
+ *
+ * @example
+ * ```typescript
+ * const inputRef = ref<HTMLInputElement>()
+ * const { isFocused } = useFocus(inputRef)
+ * ```
+ */
+export declare function useFocus(target: MaybeRef<HTMLElement | null>): {
+  isFocused: { readonly value: boolean }
+  focus: () => void
+  blur: () => void
+};
+/**
+ * Fetch data with reactive state.
+ *
+ * @example
+ * ```typescript
+ * const { data, error, isLoading } = useFetch('/api/users')
+ *
+ * // With options
+ * const { data, execute } = useFetch('/api/user', {
+ *   immediate: false
+ * })
+ * await execute()
+ * ```
+ */
+export declare function useFetch<T = unknown>(url: string | (() => string), options?: UseFetchOptions<T> & RequestInit): UseFetchReturn<T>;
+/**
+ * Async state management.
+ *
+ * @example
+ * ```typescript
+ * const { state, isLoading, error, execute } = useAsync(async () => {
+ *   const res = await fetch('/api/data')
+ *   return res.json()
+ * })
+ * ```
+ */
+export declare function useAsync<T>(fn: () => Promise<T>, options?: { immediate?: boolean }): {
+  state: { readonly value: T | null }
+  isLoading: { readonly value: boolean }
+  error: { readonly value: Error | null }
+  execute: () => Promise<T | null>
+};
+declare interface UseFetchOptions<T> {
+  immediate?: boolean
+  initialData?: T
+  refetch?: boolean
+}
+declare interface UseFetchReturn<T> {
+  data: { readonly value: T | null }
+  error: { readonly value: Error | null }
+  isLoading: { readonly value: boolean }
+  execute: () => Promise<void>
+  abort: () => void
+}
+// =============================================================================
+// Types
+// =============================================================================
+declare type MaybeRef<T> = T | { value: T }

package/dist/build-optimizer.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Analyze which directives are used in a template.
+ */
+export declare function analyzeDirectiveUsage(template: string): DirectiveUsage[];
+/**
+ * Get list of unused directives for tree-shaking.
+ */
+export declare function getUnusedDirectives(template: string, preserveDirectives?: string[]): string[];
+/**
+ * Generate tree-shaken directive loader code.
+ */
+export declare function generateTreeShakenBundle(usedDirectives: string[]): string;
+/**
+ * Find dead code branches that can be eliminated.
+ */
+export declare function findDeadBranches(template: string, constants?: Record<string, unknown>): DeadBranch[];
+/**
+ * Remove dead code branches from template.
+ */
+export declare function eliminateDeadCode(template: string, constants?: Record<string, unknown>): { content: string, removed: string[] };
+/**
+ * Evaluate a constant expression at compile time.
+ */
+export declare function evaluateConstant(expression: string, constants: Record<string, unknown>): unknown;
+/**
+ * Fold constant expressions in template.
+ */
+export declare function foldConstants(template: string, constants: Record<string, unknown>): { content: string, folded: string[] };
+/**
+ * Minify HTML content while preserving template directives.
+ */
+export declare function minifyHtml(template: string): string;
+/**
+ * Pool repeated string literals in template.
+ */
+export declare function poolStrings(template: string): {
+  content: string
+  pool: Map<string, string>
+  count: number
+};
+/**
+ * Optimize a single template with all available optimizations.
+ */
+export declare function optimizeTemplate(template: string, options?: OptimizationOptions): OptimizationResult;
+/**
+ * Create optimized build for multiple templates.
+ */
+export declare function createOptimizedBuild(templates: Map<string, string>, options?: OptimizationOptions): Promise<BuildResult>;
+/**
+ * Build-Time Optimization Module
+ *
+ * Provides tree-shaking, dead code elimination, and compile-time optimizations
+ * for stx templates to reduce bundle size and improve runtime performance.
+ *
+ * ## Features
+ *
+ * 1. **Tree-Shaking** - Remove unused directive handlers from compiled output
+ * 2. **Dead Code Elimination** - Remove unreachable template branches
+ * 3. **Constant Folding** - Pre-evaluate static expressions
+ * 4. **String Pooling** - Deduplicate repeated string literals
+ * 5. **HTML Minification** - Remove whitespace and comments from static HTML
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { optimizeTemplate, createOptimizedBuild } from 'stx/build-optimizer'
+ *
+ * // Optimize a single template
+ * const optimized = optimizeTemplate(template, { treeShake: true })
+ *
+ * // Create optimized build for multiple templates
+ * const build = await createOptimizedBuild(templates, options)
+ * ```
+ *
+ * @module build-optimizer
+ */
+/** Optimization options */
+export declare interface OptimizationOptions {
+  treeShake?: boolean
+  deadCodeElimination?: boolean
+  constantFolding?: boolean
+  stringPooling?: boolean
+  minifyHtml?: boolean
+  removeDevCode?: boolean
+  constants?: Record<string, unknown>
+  preserveDirectives?: string[]
+  target?: 'production' | 'development'
+}
+/** Optimization result */
+export declare interface OptimizationResult {
+  content: string
+  originalSize: number
+  optimizedSize: number
+  reduction: number
+  appliedOptimizations: string[]
+  removedDirectives: string[]
+  foldedConstants: string[]
+  pooledStrings: number
+  warnings: string[]
+}
+/** Build result for multiple templates */
+export declare interface BuildResult {
+  templates: Map<string, OptimizationResult>
+  directiveBundle?: string
+  stringPool?: Map<string, string>
+  totalOriginalSize: number
+  totalOptimizedSize: number
+  overallReduction: number
+  warnings: string[]
+}
+/** Directive usage info */
+declare interface DirectiveUsage {
+  name: string
+  count: number
+  locations: Array<{ line: number, column: number }>
+}
+/** Dead code branch */
+declare interface DeadBranch {
+  start: number
+  end: number
+  reason: string
+}
+export {
+  analyzeDirectiveUsage as analyzeUsage,
+  findDeadBranches as findDeadCode,
+};

package/dist/build-views.d.ts

@@ -0,0 +1,37 @@
+import type { StxOptions } from './types';
+/**
+ * Render a single STX template to HTML
+ */
+export declare function renderView(templatePath: string, props?: Record<string, unknown>, options?: Partial<StxOptions>): Promise<string>;
+/**
+ * Build all views in a directory
+ */
+export declare function buildViews(options: ViewBuildOptions): Promise<BuildResult>;
+/**
+ * Watch views directory and rebuild on changes
+ */
+export declare function watchViews(options: ViewBuildOptions, callback?: (result: BuildResult) => void): { close: () => void };
+export declare interface ViewBuildOptions {
+  viewsDir: string
+  outputDir: string
+  componentsDir?: string
+  layoutsDir?: string
+  partialsDir?: string
+  globalProps?: Record<string, unknown>
+  placeholders?: Record<string, string>
+  views?: ViewConfig[]
+  debug?: boolean
+  generateManifest?: boolean
+}
+export declare interface ViewConfig {
+  input: string
+  output?: string
+  props?: Record<string, unknown>
+}
+export declare interface BuildResult {
+  success: boolean
+  views: string[]
+  errors: Array<{ file: string; error: string }>
+  duration: number
+}
+export default buildViews;

package/dist/bundle-analyzer/collector.d.ts

@@ -0,0 +1,66 @@
+import path from 'node:path';
+/**
+ * Collect bundle statistics from a build directory
+ */
+export declare function collectBundleStats(buildDir: string, options?: CollectorOptions): Promise<BundleStats>;
+/**
+ * Format bytes to human readable string
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Parse size string to bytes
+ */
+export declare function parseSize(size: string): number;
+/**
+ * Calculate percentage
+ */
+export declare function percentage(part: number, total: number): string;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface ModuleInfo {
+  id: string
+  path: string
+  size: number
+  gzipSize: number
+  parsedSize: number
+  extension: string
+  type: ModuleType
+  imports: string[]
+  importedBy: string[]
+  hash: string
+}
+export declare interface ChunkInfo {
+  name: string
+  files: string[]
+  modules: ModuleInfo[]
+  size: number
+  gzipSize: number
+  isEntry: boolean
+  isVendor: boolean
+}
+export declare interface DuplicateModule {
+  path: string
+  count: number
+  wastedBytes: number
+  locations: string[]
+}
+export declare interface BundleStats {
+  timestamp: number
+  buildDir: string
+  chunks: ChunkInfo[]
+  totalSize: number
+  totalGzipSize: number
+  moduleCount: number
+  duplicates: DuplicateModule[]
+  byType: Record<ModuleType, { count: number; size: number; gzipSize: number }>
+  largestModules: ModuleInfo[]
+  warnings: string[]
+}
+export declare interface CollectorOptions {
+  includeSourceMaps?: boolean
+  parseImports?: boolean
+  detectDuplicates?: boolean
+  topModulesCount?: number
+}
+export type ModuleType = 'js' | 'css' | 'html' | 'image' | 'font' | 'other'