@stacksjs/stx 0.2.0 → 0.2.3

package/dist/init.d.ts

@@ -2,8 +2,38 @@
  * Initialize a new stx file with the specified name
  */
 export declare function initFile(fileName?: string, options?: InitOptions): Promise<boolean>;
-// Interface for init options
+/**
+ * Available template presets with descriptions
+ */
+export declare const TEMPLATE_PRESETS: {
+  basic: {
+  description: 'Simple page with script, style, and template sections'
+};
+  component: {
+  description: 'Reusable component with props and slots'
+};
+  layout: {
+  description: 'Layout template with sections and yields'
+};
+  blog: {
+  description: 'Blog post with frontmatter-style variables'
+};
+  api: {
+  description: 'API endpoint template with JSON response'
+};
+  app: {
+  description: 'Full app with stores and components'
+}
+};
+/**
+ * Options for initializing a new stx file
+ */
 declare interface InitOptions {
   force?: boolean
   template?: string
-}
+  preset?: TemplatePreset
+}
+/**
+ * Built-in template presets
+ */
+declare type TemplatePreset = 'basic' | 'component' | 'layout' | 'blog' | 'api' | 'app'

package/dist/interactive.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Start interactive CLI mode
+ */
+export declare function startInteractive(options?: InteractiveOptions): Promise<void>;
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface InteractiveOptions {
+  context?: Record<string, any>
+  cwd?: string
+  verbose?: boolean
+  historyFile?: string
+  maxHistory?: number
+}

package/dist/internal-markdown.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Parse YAML frontmatter from markdown content
+ * Frontmatter is delimited by --- at the start of the file
+ */
+export declare function parseFrontmatter(content: string): FrontmatterResult;
+/**
+ * Convert markdown to HTML
+ * Simple implementation that handles common markdown patterns
+ */
+export declare function parseMarkdown(content: string, options?: MarkdownOptions): string;
+/**
+ * Internal markdown utilities to replace ts-md dependency
+ * Provides frontmatter parsing and markdown to HTML conversion
+ */
+export declare interface FrontmatterResult {
+  data: Record<string, unknown>
+  content: string
+}
+export declare interface MarkdownOptions {
+  gfm?: boolean
+  breaks?: boolean
+}

package/dist/jsx-runtime.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Create a VNode. This is the function Bun's JSX transpiler calls.
+ *
+ * @param type - Tag name string, component function, or Fragment symbol
+ * @param props - Props object (may include children)
+ * @param key - Optional key for list reconciliation
+ */
+export declare function jsx(type: string | ComponentFunction | typeof Fragment, props: Record<string, any> | null, key?: string | number | null): VNode;
+/**
+ * Render a VNode tree to an HTML string.
+ * This is the primary SSR function.
+ *
+ * @param vnode - The VNode or string to render
+ * @returns HTML string
+ */
+export declare function renderToString(vnode: VNode | string | null | undefined | boolean | number): string;
+/**
+ * Render a VNode tree to a readable stream for streaming SSR.
+ */
+export declare function renderToStream(vnode: VNode | string): ReadableStream<string>;
+/**
+ * Render a VNode tree to real DOM nodes.
+ *
+ * @param vnode - The VNode or string to render
+ * @param container - The parent DOM element to append to
+ */
+export declare function renderToDOM(vnode: VNode | string | null | undefined | boolean | number, container: Element): void;
+/**
+ * Conditional rendering component — equivalent to v-if / @if.
+ *
+ * ```tsx
+ * <Show when={isVisible} fallback={<p>Hidden</p>}>
+ *   <div>Visible content</div>
+ * </Show>
+ * ```
+ */
+export declare function Show(props: { when: any, fallback?: VNode | string | null, children?: any }): VNode | string | null;
+/**
+ * List rendering component — equivalent to v-for / @foreach.
+ *
+ * ```tsx
+ * <For each={items}>
+ *   {(item, index) => <div key={item.id}>{item.name}</div>}
+ * </For>
+ * ```
+ */
+export declare function For<T>(props: { each: T[] | undefined | null, fallback?: VNode | string | null, children: ((item: T, index: number) => VNode | string) | Array<(item: T, index: number) => VNode | string> }): VNode | string | null;
+/**
+ * Portal/Teleport component — renders children to a different DOM target.
+ * Only effective on client-side; SSR renders children inline.
+ *
+ * ```tsx
+ * <Portal to="body">
+ *   <div class="modal">Modal content</div>
+ * </Portal>
+ * ```
+ */
+export declare function Portal(props: { to: string, children?: any }): VNode | string | null;
+/**
+ * Create a VNode using the h() function syntax (alternative to JSX).
+ *
+ * ```ts
+ * import { h } from '@stacksjs/stx/jsx-runtime'
+ *
+ * const vnode = h('div', { class: 'container' },
+ *   h('h1', null, 'Hello'),
+ *   h('p', null, 'World')
+ * )
+ * ```
+ */
+export declare function h(type: string | ComponentFunction | typeof Fragment, props?: Record<string, any> | null, ...children: any[]): VNode;
+/** Fragment symbol - renders children without a wrapper element */
+export declare const Fragment: unique symbol;
+/**
+ * Same as jsx — Bun's transpiler uses jsxs when there are multiple static children.
+ */
+export declare const jsxs: unknown;
+/**
+ * Development version of jsx with extra validation.
+ */
+export declare const jsxDEV: unknown;
+/**
+ * STX JSX Runtime
+ *
+ * Self-made JSX runtime for stx — no React, no Preact, no external dependencies.
+ * This module provides the jsx/jsxs/Fragment functions that Bun's JSX transpiler calls,
+ * plus renderToString() for SSR and renderToDOM() for client-side rendering.
+ *
+ * Usage in tsconfig.json:
+ * ```json
+ * {
+ *   "compilerOptions": {
+ *     "jsx": "react-jsx",
+ *     "jsxImportSource": "@stacksjs/stx"
+ *   }
+ * }
+ * ```
+ *
+ * @module jsx-runtime
+ */
+/** Virtual DOM node representation */
+export declare interface VNode {
+  type: string | ComponentFunction | typeof Fragment
+  props: Record<string, any> | null
+  children: Array<VNode | string>
+  key?: string | number | null
+  ref?: string | ((el: any) => void) | null
+}
+/** Function component type */
+export type ComponentFunction = (props: Record<string, any>) => VNode | string | null

package/dist/keep-alive.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Process @keepAlive directives in templates.
+ *
+ * Syntax:
+ *   @keepAlive
+ *     <content to cache>
+ *   @endkeepAlive
+ *
+ * With options:
+ *   @keepAlive(max: 10, include: 'ComponentA,ComponentB')
+ */
+export declare function processKeepAliveDirectives(template: string, _context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Create a keep-alive cache programmatically.
+ */
+export declare function createKeepAliveCache(options?: KeepAliveOptions): KeepAliveCache;
+/**
+ * Check if a component should be cached based on filters.
+ */
+export declare function shouldCacheComponent(componentName: string, cache: KeepAliveCache): boolean;
+/**
+ * Generate CSS for keep-alive styling.
+ */
+export declare function generateKeepAliveCSS(): string;
+/**
+ * Generate client-side runtime for keep-alive.
+ */
+export declare function generateKeepAliveRuntime(): string;
+/**
+ * Hook called when a component is activated from cache.
+ * Use in client-side scripts.
+ */
+export declare function onActivated(callback: (detail: { key: string; keepAliveId: string; cachedAt: number }) => void): void;
+/**
+ * Hook called when a component is deactivated and cached.
+ * Use in client-side scripts.
+ */
+export declare function onDeactivated(callback: (detail: { key: string; keepAliveId: string }) => void): void;
+/**
+ * STX Keep-Alive
+ *
+ * Caches component instances to preserve state when toggling visibility.
+ * Similar to Vue's <KeepAlive> component.
+ *
+ * @module keep-alive
+ *
+ * @example
+ * ```html
+ * @keepAlive
+ *   @if (currentTab === 'settings')
+ *     <SettingsPanel />
+ *   @elseif (currentTab === 'profile')
+ *     <ProfilePanel />
+ *   @endif
+ * @endkeepAlive
+ * ```
+ *
+ * With options:
+ * ```html
+ * @keepAlive(max: 10, include: 'Settings,Profile', exclude: 'Debug')
+ *   <component :is="currentComponent" />
+ * @endkeepAlive
+ * ```
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface KeepAliveOptions {
+  max?: number
+  include?: string
+  exclude?: string
+  id?: string
+}
+export declare interface CachedComponent {
+  key: string
+  html: string
+  state: Record<string, unknown>
+  cachedAt: number
+  scrollPositions: Map<string, { top: number; left: number }>
+}
+export declare interface KeepAliveCache {
+  id: string
+  cache: Map<string, CachedComponent>
+  max: number
+  include: string[] | null
+  exclude: string[] | null
+}

package/dist/lazy-loader.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Default lazy-loaded directive registry
+ */
+export declare function createDirectiveRegistry(): DirectiveLoaderRegistry;
+/**
+ * Create a lazy module that loads on first access
+ */
+export declare function createLazyModule<T>(loader: ModuleLoader<T>): {
+  get: () => Promise<T>
+  isLoaded: () => boolean
+  preload: () => Promise<void>
+};
+/**
+ * Batch load multiple modules with progress callback
+ */
+export declare function batchLoad<T>(loader: LazyLoader<T>, names: string[], onProgress?: (loaded: number, total: number, name: string) => void): Promise<Map<string, T>>;
+/**
+ * Global lazy loader instance
+ */
+export declare const globalLoader: LazyLoader<unknown>;
+/**
+ * Global directive registry
+ */
+export declare const directiveRegistry: DirectiveLoaderRegistry;
+/**
+ * Lazy loader options
+ */
+export declare interface LazyLoaderOptions {
+  preload?: string[]
+  timeout?: number
+  debug?: boolean
+  onError?: (name: string, error: Error) => void
+}
+/**
+ * Directive processor interface
+ */
+export declare interface DirectiveProcessor {
+  process: (content: string, params?: string, context?: Record<string, unknown>) => string | Promise<string>
+  name?: string
+  hasEndTag?: boolean
+}
+/**
+ * Lazy Loading for Directive Processors
+ *
+ * Provides lazy loading capabilities for directive processors to reduce
+ * initial load time and memory usage.
+ *
+ * ## Features
+ *
+ * - On-demand loading of directive processors
+ * - Module caching to prevent re-imports
+ * - Support for both sync and async loading
+ * - Automatic dependency resolution
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const loader = new LazyLoader()
+ *
+ * // Register lazy directive
+ * loader.register('markdown', () => import('./markdown'))
+ *
+ * // Load when needed
+ * const markdown = await loader.load('markdown')
+ * ```
+ *
+ * @module lazy-loader
+ */
+/**
+ * Module loader function
+ */
+export type ModuleLoader<T = unknown> = () => Promise<T> | T
+/**
+ * Module status
+ */
+export type ModuleStatus = 'pending' | 'loading' | 'loaded' | 'error'
+/**
+ * Lazy loader for directive processors
+ */
+export declare class LazyLoader<T = unknown> {
+  private modules: Map<string, ModuleInfo<T>>;
+  private options: LazyLoaderOptions;
+  constructor(options?: LazyLoaderOptions);
+  register(name: string, loader: ModuleLoader<T>, dependencies?: string[]): void;
+  registerAll(modules: Record<string, ModuleLoader<T>>): void;
+  has(name: string): boolean;
+  getStatus(name: string): ModuleStatus | null;
+  isLoaded(name: string): boolean;
+  load(name: string): Promise<T>;
+  loadAll(names: string[]): Promise<T[]>;
+  loadSync(name: string): T;
+  preload(names: string[]): Promise<void>;
+  unload(name: string): boolean;
+  unloadAll(): void;
+  getStats(): {
+    registered: number
+    loaded: number
+    pending: number
+    errors: number
+    totalLoadTime: number
+    modules: Array<{
+      name: string
+      status: ModuleStatus
+      loadCount: number
+      loadTime?: number
+    }>
+  };
+  private loadWithTimeout(name: string, loader: ModuleLoader<T>): Promise<T>;
+}
+/**
+ * Lazy loader specifically for directive processors
+ */
+export declare class DirectiveLoaderRegistry {
+  private loader: LazyLoader<DirectiveProcessor | { default: DirectiveProcessor }>;
+  private directiveMap: Map<string, string>;
+  constructor(options?: LazyLoaderOptions);
+  registerDirective(directiveName: string, moduleName: string, loader: ModuleLoader<DirectiveProcessor | { default: DirectiveProcessor }>): void;
+  getProcessor(directiveName: string): Promise<DirectiveProcessor | null>;
+  hasDirective(directiveName: string): boolean;
+  getDirectiveNames(): string[];
+  preloadDirectives(directiveNames: string[]): Promise<void>;
+}

package/dist/loading-indicator.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Create a loading indicator instance (composable-style)
+ */
+export declare function useLoadingIndicator(userOptions?: LoadingIndicatorOptions): LoadingIndicatorInstance;
+/**
+ * Initialize automatic loading indicator for page navigation
+ * Call this once in your app to enable automatic loading on route changes
+ */
+export declare function initLoadingIndicator(userOptions?: LoadingIndicatorOptions): void;
+/**
+ * Generate the HTML for the loading indicator component
+ * This is used by the STX compiler for <stx-loading-indicator />
+ */
+export declare function generateLoadingIndicatorHtml(options?: LoadingIndicatorOptions): string;
+export declare interface LoadingIndicatorOptions {
+  color?: string
+  initialColor?: string
+  height?: string
+  duration?: number
+  throttle?: number
+  autoFinish?: boolean
+  zIndex?: number
+}
+export declare interface LoadingIndicatorState {
+  isLoading: boolean
+  progress: number
+  error: boolean
+}
+export declare interface LoadingIndicatorInstance {
+  start: () => void
+  set: (value: number) => void
+  finish: () => void
+  clear: () => void
+  state: LoadingIndicatorState
+}
+export default {
+  useLoadingIndicator,
+  initLoadingIndicator,
+  generateLoadingIndicatorHtml,
+};

package/dist/loops.d.ts

@@ -1,4 +1,25 @@
+import type { StxOptions } from './types';
 /**
  * Process loops (@foreach, @for, @while, @forelse)
+ *
+ * Loop Configuration (via options.loops):
+ * - maxWhileIterations: Safety limit for @while loops (default: 1000)
+ * - useAltLoopVariable: Use $loop instead of loop (default: false)
+ *
+ * Loop Context Variables:
+ * Within @foreach loops, a loop context object is available:
+ * - loop.index: Current zero-based index
+ * - loop.iteration: Current one-based iteration count
+ * - loop.first: Boolean, true if first iteration
+ * - loop.last: Boolean, true if last iteration
+ * - loop.count: Total number of items
+ *
+ * If options.loops.useAltLoopVariable is true, use $loop instead of loop
+ * to avoid conflicts with user variables named 'loop'.
+ *
+ * @param template - Template string to process
+ * @param context - Template context with variables
+ * @param filePath - Path to template file for error messages
+ * @param options - Optional stx configuration
  */
-export declare function processLoops(template: string, context: Record<string, any>, filePath: string): string;
+export declare function processLoops(template: string, context: Record<string, any>, filePath: string, options?: StxOptions): string;

package/dist/media/client/blur-up.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Initialize blur-up effect for an image
+ *
+ * @example
+ * ```typescript
+ * const img = document.querySelector('img.has-placeholder')
+ * initBlurUp(img, { duration: 500 })
+ * ```
+ */
+export declare function initBlurUp(img: HTMLImageElement, options?: BlurUpOptions): void;
+/**
+ * Render a thumbhash to a canvas element
+ *
+ * Based on https://github.com/evanw/thumbhash
+ */
+export declare function renderThumbhashToCanvas(hash: Uint8Array, canvas: HTMLCanvasElement): void;
+/**
+ * Decode a thumbhash to RGBA pixel data
+ *
+ * This is a minimal decoder based on the thumbhash spec.
+ * Returns a 32x32 RGBA image.
+ */
+export declare function thumbHashToRGBA(hash: Uint8Array): { w: number; h: number; rgba: Uint8ClampedArray };
+/**
+ * Convert a thumbhash to a data URL
+ */
+export declare function thumbHashToDataURL(hash: Uint8Array): string;
+/**
+ * Parse a base64-encoded thumbhash string
+ */
+export declare function parseThumbhashString(base64: string): Uint8Array;
+/**
+ * Crossfade transition between two elements
+ */
+export declare function crossfadeTransition(from: HTMLElement, to: HTMLElement, duration?: number): Promise<void>;
+/**
+ * Initialize blur-up for all elements with data-stx-blur-up
+ */
+export declare function initAllBlurUp(options?: BlurUpOptions): void;
+/**
+ * Generate the client-side blur-up runtime script
+ */
+export declare function generateBlurUpRuntime(): string;
+/**
+ * Generate CSS for blur-up effect
+ */
+export declare function generateBlurUpCSS(): string;
+/**
+ * STX Media - Client-Side Blur-Up Animation
+ *
+ * Smooth blur-up transition from placeholder to full image.
+ * Supports thumbhash, blur LQIP, and color placeholders.
+ *
+ * @module media/client/blur-up
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface BlurUpOptions {
+  duration?: number
+  easing?: string
+  removePlaceholder?: boolean
+  loadedClass?: string
+  loadingClass?: string
+}

package/dist/media/client/index.d.ts

@@ -0,0 +1,77 @@
+import { generateBlurUpRuntime, generateBlurUpCSS } from './blur-up';
+import { generateLazyLoadRuntime } from './lazy-load';
+import { generateUploadRuntime } from './upload-handler';
+/**
+ * Generate the complete media client runtime
+ */
+export declare function generateMediaRuntime(): { script: string; css: string };
+/**
+ * Generate minified media runtime for production
+ */
+export declare function generateMinifiedMediaRuntime(): { script: string; css: string };
+export {
+  // Types
+  type LazyLoadOptions,
+
+  // Feature detection
+  isNativeLazySupported,
+  isIntersectionObserverSupported,
+
+  // Initialization
+  initLazyLoading,
+  loadElement,
+
+  // Manual loading
+  lazyLoad,
+  lazyLoadAll,
+
+  // Observer utilities
+  createLazyObserver,
+  observeElement,
+  disconnectObserver,
+
+  // Runtime generation
+  generateLazyLoadRuntime,
+} from './lazy-load';
+export {
+  // Types
+  type BlurUpOptions,
+
+  // Initialization
+  initBlurUp,
+  initAllBlurUp,
+
+  // Thumbhash utilities
+  renderThumbhashToCanvas,
+  thumbHashToRGBA,
+  thumbHashToDataURL,
+  parseThumbhashString,
+
+  // Transitions
+  crossfadeTransition,
+
+  // Runtime generation
+  generateBlurUpRuntime,
+  generateBlurUpCSS,
+} from './blur-up';
+export {
+  // Types
+  type UploadHandlerOptions,
+  type UploadProgress,
+  type UploadResult,
+  type FileValidationResult,
+
+  // Validation
+  validateFile,
+
+  // Upload functions
+  uploadFile,
+  uploadFiles,
+
+  // Preview generation
+  generateImagePreview,
+  generateVideoPreview,
+
+  // Runtime generation
+  generateUploadRuntime,
+} from './upload-handler';

package/dist/media/client/lazy-load.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Check if native lazy loading is supported
+ */
+export declare function isNativeLazySupported(): boolean;
+/**
+ * Check if IntersectionObserver is supported
+ */
+export declare function isIntersectionObserverSupported(): boolean;
+/**
+ * Initialize lazy loading for all matching elements
+ *
+ * @example
+ * ```typescript
+ * // Initialize with default options
+ * initLazyLoading()
+ *
+ * // Initialize with custom options
+ * initLazyLoading({
+ *   rootMargin: '100px',
+ *   onLoaded: (el) => console.log('Loaded:', el)
+ * })
+ * ```
+ */
+export declare function initLazyLoading(options?: LazyLoadOptions): () => void;
+/**
+ * Load a single lazy element
+ */
+export declare function loadElement(element: HTMLElement, options?: LazyLoadOptions): void;
+/**
+ * Manually trigger loading for a specific element
+ */
+export declare function lazyLoad(element: HTMLElement): void;
+/**
+ * Manually trigger loading for all matching elements
+ */
+export declare function lazyLoadAll(selector?: string): void;
+/**
+ * Create a reusable intersection observer
+ */
+export declare function createLazyObserver(options?: LazyLoadOptions): IntersectionObserver;
+/**
+ * Observe a new element with an existing observer
+ */
+export declare function observeElement(observer: IntersectionObserver, element: HTMLElement): void;
+/**
+ * Unobserve all elements and disconnect
+ */
+export declare function disconnectObserver(observer: IntersectionObserver): void;
+/**
+ * Generate the client-side lazy loading runtime script
+ */
+export declare function generateLazyLoadRuntime(): string;
+/**
+ * STX Media - Client-Side Lazy Loading
+ *
+ * IntersectionObserver-based lazy loading for images and media.
+ * Supports native loading="lazy" with intelligent fallback.
+ *
+ * @module media/client/lazy-load
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface LazyLoadOptions {
+  root?: Element | null
+  rootMargin?: string
+  threshold?: number | number[]
+  useNative?: boolean
+  selector?: string
+  onLoad?: (element: HTMLElement) => void
+  onLoaded?: (element: HTMLElement) => void
+  onError?: (element: HTMLElement, error: Error) => void
+}