@stacksjs/stx 0.0.9 → 0.1.6

package/dist/client.d.ts

@@ -1,36 +1,20 @@
-declare type IslandHandlers = Record<string, () => Promise<any>>
-
-type IslandHydrationFn = (element: any, props: any) => void | Promise<void>
-
-const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined'
-
-async function hydrateIsland(
-  element: any,
-  name: string,
-  handler: () => Promise<any>,
-): Promise<void> {
-  if (!isBrowser) return
-
-  try {
-    const id = element.getAttribute('data-island-id')
-    const propsScript = document.querySelector(`script[data-island-props="${id}"]`)
-    const props = propsScript ? JSON.parse(propsScript.textContent || '{}') : {}
-
-    const module = await handler()
-    const hydrateFn: IslandHydrationFn = module.default || module.hydrate
-
-    if (typeof hydrateFn !== 'function') {
-      console.error(`Island handler for "${name}" does not export a valid hydration function`)
-      return
-    }
-
-    await hydrateFn(element, props)
-
-    element.setAttribute('data-hydrated', 'true')
-  }
-  catch (error) {
-    console.error(`Failed to hydrate island "${name}":`, error)
-  }
-}
+/**
+ * Hydrate all islands with the given handlers
+ */
 export declare function hydrateIslands(handlers: IslandHandlers): void;
-export declare function preloadIslandHandlers(handlers: IslandHandlers): void;
+/**
+ * Add preload links for island scripts
+ */
+export declare function preloadIslandHandlers(handlers: IslandHandlers): void;
+/**
+ * Client-side hydration functionality for stx templates
+ * This file is meant to be used in the browser only
+ */
+/**
+ * Island handler registry
+ */
+declare type IslandHandlers = Record<string, () => Promise<any>>
+/**
+ * Island hydration function
+ */
+declare type IslandHydrationFn = (element: any, props: any) => void | Promise<void>

package/dist/components.d.ts

@@ -0,0 +1,6 @@
+import type { CustomDirective } from './types';
+/**
+ * Register component directives
+ */
+export declare function registerComponentDirectives(): CustomDirective[];
+export declare const componentDirective: CustomDirective;

package/dist/conditionals.d.ts

@@ -1,4 +1,20 @@
+/**
+ * Process switch statements (@switch, @case, @default)
+ */
+export declare function processSwitchStatements(template: string, context: Record<string, any>, filePath: string): string;
+/**
+ * Process conditionals (@if, @elseif, @else, @unless)
+ */
 export declare function processConditionals(template: string, context: Record<string, any>, filePath: string): string;
+/**
+ * Process @auth and permissions directives
+ */
 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 processEnvDirective(template: string, context: Record<string, any>, filePath?: string): string;
+/**
+ * Process @env directive to conditionally render content based on environment
+ */
+export declare function processEnvDirective(template: string, _context: Record<string, any>, _filePath?: string): string;

package/dist/config.d.ts

@@ -1,4 +1,8 @@
-import type { StxConfig } from './types';
-
+import type { StxOptions } from './types';
+/**
+ * Helper function to define stx configuration
+ */
+export declare function defineStxConfig(config: StxOptions): StxOptions;
 export declare const defaultConfig: StxConfig;
+// eslint-disable-next-line antfu/no-top-level-await
 export declare const config: StxConfig;

package/dist/csrf.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Generate a CSRF token
+ */
+export declare function generateCsrfToken(length?: number): string;
+/**
+ * Get the current CSRF token, generating one if it doesn't exist
+ */
+export declare function getCsrfToken(): string;
+/**
+ * Reset the CSRF token (mainly for testing)
+ */
+export declare function resetCsrfToken(): void;
+/**
+ * Set a specific CSRF token (useful for server frameworks that have their own token generation)
+ */
+export declare function setCsrfToken(token: string): void;
+/**
+ * Generate a CSRF input field HTML
+ */
+export declare function csrfField(inputName?: string): string;
+/**
+ * Process @csrf directives in templates
+ */
+export declare function processCsrfDirectives(template: string): string;
+/**
+ * Middleware-like function to verify CSRF token
+ */
+export declare function verifyCsrfToken(token: string): boolean;

package/dist/custom-directives.d.ts

@@ -1,6 +1,5 @@
-import type { CustomDirective, StxOptions } from './types';
-
-export declare function processCustomDirectives(template: string, context: Record<string, any>, filePath: string, options: StxOptions): Promise<string>;
-declare function processDirectiveWithEndTag(template: string, directive: CustomDirective, context: Record<string, any>, filePath: string, options: StxOptions): Promise<string>;
-declare function processDirectiveWithoutEndTag(template: string, directive: CustomDirective, context: Record<string, any>, filePath: string, options: StxOptions): Promise<string>;
-declare function parseDirectiveParams(paramString: string): string[];
+import type { StxOptions } from './types';
+/**
+ * Process all custom directives registered in the app
+ */
+export declare function processCustomDirectives(template: string, context: Record<string, any>, filePath: string, options: StxOptions): Promise<string>;

package/dist/dev-server.d.ts

@@ -0,0 +1,21 @@
+import type { SyntaxHighlightTheme } from './types';
+// Build and serve a specific stx file
+export declare function serveStxFile(filePath: string, options?: DevServerOptions): Promise<boolean>;
+// Build and serve multiple files (stx and Markdown)
+export declare function serveMultipleStxFiles(filePaths: string[], options?: DevServerOptions): Promise<boolean>;
+// Define types for dev server options
+export declare interface DevServerOptions {
+  port?: number
+  watch?: boolean
+  stxOptions?: any
+  markdown?: {
+    syntaxHighlighting?: {
+      serverSide?: boolean
+      enabled?: boolean
+      defaultTheme?: SyntaxHighlightTheme
+      highlightUnknownLanguages?: boolean
+      additionalThemes?: SyntaxHighlightTheme[]
+    }
+  }
+  cache?: boolean
+}

package/dist/docs.d.ts

@@ -1,15 +1,48 @@
-import type { ComponentDoc, DirectiveDoc, TemplateDoc } from './types';
-
+import { config } from './config';
+import type { ComponentDoc, ComponentPropDoc, DirectiveDoc, DocGeneratorConfig, TemplateDoc } from './types';
+/**
+ * Extract component properties from a component file
+ */
 export declare function extractComponentProps(componentPath: string): Promise<ComponentPropDoc[]>;
+/**
+ * Extract component description from a component file
+ */
 export declare function extractComponentDescription(componentPath: string): Promise<string>;
-export declare function generateComponentDoc(componentPath: string, isWebComponent?: boolean, webComponentTag?: string): Promise<ComponentDoc>;
+/**
+ * Generate documentation for a component
+ */
+export declare function generateComponentDoc(componentPath: string, isWebComponent?: any, webComponentTag?: string): Promise<ComponentDoc>;
+/**
+ * Find all component files in a directory
+ */
 export declare function findComponentFiles(componentsDir: string): Promise<string[]>;
+/**
+ * Generate documentation for all components
+ */
 export declare function generateComponentsDocs(componentsDir: string, webComponentsConfig?: any): Promise<ComponentDoc[]>;
+/**
+ * Generate documentation for templates
+ */
 export declare function generateTemplatesDocs(templatesDir: string): Promise<TemplateDoc[]>;
+/**
+ * Generate documentation for directives
+ */
 export declare function generateDirectivesDocs(customDirectives?: any[]): Promise<DirectiveDoc[]>;
+/**
+ * Format documentation as Markdown
+ */
 export declare function formatDocsAsMarkdown(componentDocs?: ComponentDoc[], templateDocs?: TemplateDoc[], directiveDocs?: DirectiveDoc[], extraContent?: string): string;
+/**
+ * Format documentation as HTML
+ */
 export declare function formatDocsAsHtml(componentDocs?: ComponentDoc[], templateDocs?: TemplateDoc[], directiveDocs?: DirectiveDoc[], extraContent?: string): string;
+/**
+ * Format documentation as JSON
+ */
 export declare function formatDocsAsJson(componentDocs?: ComponentDoc[], templateDocs?: TemplateDoc[], directiveDocs?: DirectiveDoc[], extraContent?: string): string;
+/**
+ * Generate documentation
+ */
 export declare function generateDocs(options: {
   componentsDir?: string
   templatesDir?: string
@@ -17,4 +50,7 @@ export declare function generateDocs(options: {
   customDirectives?: any[]
   config: Partial<DocGeneratorConfig>
 }): Promise<boolean>;
+/**
+ * Documentation generation command handler for CLI
+ */
 export declare function docsCommand(options: any): Promise<boolean>;

package/dist/error-handling.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Enhanced error reporting with better context
+ */
+export declare function createEnhancedError(type: string, message: string, context: ErrorContext): string;
+/**
+ * Safe wrapper for potentially dangerous operations
+ */
+export declare function safeExecute<T>(operation: () => T, fallback: T, errorHandler?: (error: Error) => void): T;
+/**
+ * Async version of safe wrapper
+ */
+export declare function safeExecuteAsync<T>(operation: () => Promise<T>, fallback: T, errorHandler?: (error: Error) => void): Promise<T>;
+/**
+ * Validation utilities
+ */
+export declare const validators: {
+  /**
+   * Validate file path is safe
+   */
+  isValidFilePath(filePath: string): unknown
+};
+/**
+ * Error recovery strategies
+ */
+export declare const errorRecovery: {
+  /**
+   * Attempt to fix common template syntax errors
+   */
+  fixCommonSyntaxErrors(template: string): unknown;
+  /**
+   * Create fallback content for failed template sections
+   */
+  createFallbackContent(sectionType: string, error: Error): unknown
+};
+// Global error logger instance
+export declare const errorLogger: ErrorLogger;
+/**
+ * Development mode helpers
+ */
+export declare const devHelpers: {
+  /**
+   * Check if we're in development mode
+   */
+  isDevelopment(): boolean {
+    return process.env.NODE_ENV === 'development' || process.env.stx_DEBUG === 'true'
+  },
+
+  /**
+   * Log detailed error information in development
+   */
+  logDetailedError(error: Error, context?: any): void {
+    if (!this.isDevelopment())
+      return
+
+    console.error('=== stx Detailed Error ===')
+    console.error('Error: unknown
+};
+/**
+ * Error context information
+ */
+export declare interface ErrorContext {
+  filePath: string
+  template: string
+  offset: number
+  match: string
+}
+/**
+ * Custom error types for better error classification
+ */
+export declare class StxError extends Error {
+  public code: string;
+  public filePath?: string;
+  public line?: number;
+  public column?: number;
+  public context?: string;
+  constructor(message: string, code: string, filePath?: string, line?: number, column?: number, context?: string);
+}
+export declare class StxSyntaxError extends StxError {
+  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string);
+}
+export declare class StxRuntimeError extends StxError {
+  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string);
+}
+export declare class StxSecurityError extends StxError {
+  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string);
+}
+export declare class StxFileError extends StxError {
+  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string);
+}
+/**
+ * Error logging and monitoring
+ */
+export declare class ErrorLogger {
+  private errors: Array<{ timestamp: Date, error: Error, context?: any }>;
+  private maxErrors: any;
+  log(error: Error, context?: any): void;
+  getRecentErrors(limit?: any): Array<{ timestamp: Date, error: Error, context?: any }>;
+  getErrorsByType(errorType: string): Array<{ timestamp: Date, error: Error, context?: any }>;
+  clear(): void;
+  getStats(): { total: number, byType: Record<string, number> };
+}

package/dist/expressions.d.ts

@@ -1,9 +1,48 @@
-export declare type FilterFunction = (value: any, ...args: any[]) => any
-
-let globalContext: Record<string, any> = {}
+/**
+ * Set global context for filters
+ */
 export declare function setGlobalContext(context: Record<string, any>): void;
+/**
+ * HTML escape function to prevent XSS
+ */
 export declare function escapeHtml(unsafe: string): string;
+/**
+ * Process template expressions including variables, filters, and operations
+ */
 export declare function processExpressions(template: string, context: Record<string, any>, filePath: string): string;
+/**
+ * Apply filters to a value
+ */
 export declare function applyFilters(value: any, filterExpression: string, context: Record<string, any>): any;
+/**
+ * Evaluate an expression within the given context
+ * @param {string} expression - The expression to evaluate
+ * @param {Record<string, any>} context - The context object containing variables
+ * @param {boolean} silent - Whether to silently handle errors (return undefined) or throw
+ * @returns The evaluated result
+ */
 export declare function evaluateExpression(expression: string, context: Record<string, any>, silent?: boolean): any;
-export declare function unescapeHtml(html: string): string;
+/**
+ * HTML unescape function to reverse escapeHtml
+ */
+export declare function unescapeHtml(html: string): string;
+export declare const defaultFilters: {
+  // String transformation filters
+  uppercase: (value: any) => unknown;
+  lowercase: (value: any) => unknown;
+  capitalize: (value: any) => unknown;
+  // Number filters
+  number: (value: any, decimals: number?) => unknown;
+  // Array filters
+  join: () => unknown;
+  // Safety filters
+  escape: (value: any) => unknown;
+  // Translation filter
+  translate: (value: any, params: Record<string, any> = {}) => unknown;
+  // Short alias for translate
+  t: (value: any, params: Record<string, any> = {}) => unknown
+};
+/**
+ * Add basic filter support to expressions
+ */
+export type FilterFunction = (value: any, ...args: any[]) => any

package/dist/formatter.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Format stx file content
+ */
+export declare function formatStxContent(content: string, options?: FormatterOptions): string;
+/**
+ * stx file formatter for automatically formatting .stx files
+ */
+/* eslint-disable regexp/no-super-linear-backtracking */
+export declare interface FormatterOptions {
+  indentSize?: number
+  useTabs?: boolean
+  maxLineLength?: number
+  normalizeWhitespace?: boolean
+  sortAttributes?: boolean
+  trimTrailingWhitespace?: boolean
+}

package/dist/forms.d.ts

@@ -1,31 +1,21 @@
 import type { StxOptions } from './types';
-
-declare function genId(): string;
+/**
+ * Process all form-related directives
+ */
 export declare function processForms(template: string, context: Record<string, any>, _filePath: string, _options: StxOptions): string;
+/**
+ * Process basic form directives (@csrf, @method)
+ */
 export declare function processBasicFormDirectives(template: string, context: Record<string, any>): string;
+/**
+ * Process form input directives
+ */
 export declare function processFormInputDirectives(template: string, context: Record<string, any>): string;
-declare const name: unknown;
-declare const attrs: unknown;
-declare const type: unknown;
-declare const existingClass: unknown;
-declare const attrs: unknown;
-declare const hasError: unknown;
-declare const existingClass: unknown;
-declare const attrs: unknown;
-declare const hasError: unknown;
-declare const existingClass: unknown;
-declare const isSelected: oldValue;
-declare const attrs: unknown;
-declare const isChecked: oldValues;
-declare const existingClass: unknown;
-declare const attrs: unknown;
-declare const isChecked: unknown;
-declare const className: unknown;
-declare const attrs: unknown;
-declare const className: unknown;
+/**
+ * Process @error directive for form validation
+ */
 export declare function processErrorDirective(template: string, context: Record<string, any>): string;
-declare function hasFieldError(field: string, context: Record<string, any>): boolean;
-declare function getErrorMessage(field: string, context: Record<string, any>): string;
-declare function getOldValue(field: string, context: Record<string, any>): any;
-declare function parseAttributes(attributesStr: string): string;
+/**
+ * Process @form directives for forms
+ */
 export declare function processFormDirectives(template: string, context: Record<string, any>): string;

package/dist/i18n.d.ts

@@ -1,22 +1,19 @@
-import type { I18nConfig, StxOptions } from './types';
-
-export declare const defaultI18nConfig: I18nConfig;
-declare const translationsCache: Record<string, Record<string, any>>;
+import type { StxOptions } from './types';
+/**
+ * Load a translation file
+ */
 export declare function loadTranslation(locale: string, options: StxOptions): Promise<Record<string, any>>;
-declare function parseYaml(content: string): Promise<Record<string, any>>;
-declare function getFileExtension(format: string): string;
-export declare function getTranslation(key: string,
-  translations: Record<string, any>,
-  fallbackToKey: boolean = true,
-  params: Record<string, any> = {},): string;
+/**
+ * Get a translation by key
+ */
+export declare function getTranslation(key: string, translations: Record<string, any>, fallbackToKey?: boolean, params?: Record<string, any>): string;
+/**
+ * Process @translate directive
+ */
 export declare function processTranslateDirective(template: string, context: Record<string, any>, filePath: string, options: StxOptions): Promise<string>;
-declare const i18nConfig: {};
-declare const translations: unknown;
-declare const approaches: Array<(() => unknown) | (() => unknown) | (() => unknown)>;
-declare const translation: unknown;
-declare const matches: Array<((...args: any[]) => unknown)>;
-declare const approaches: Array<(() => unknown) | (() => unknown) | (() => unknown)>;
-declare function replaceAsync(str: string, regex: RegExp, asyncFn: (
-    match, ...groups?: any[]
-  )): Promise<string>;
-export declare function createTranslateFilter(translations: Record<string, any>, fallbackToKey?: boolean): (value: string, params?: Record<string, any>) => string;
+/**
+ * Create a translation filter for expressions
+ */
+export declare function createTranslateFilter(translations: Record<string, any>, fallbackToKey?: boolean): (value: string, params?: Record<string, any>) => string;
+// Default i18n configuration
+export declare const defaultI18nConfig: I18nConfig;

package/dist/includes.d.ts

@@ -1,21 +1,24 @@
 import type { StxOptions } from './types';
-
-export declare const partialsCache: Map<string, string>;
+/**
+ * Clear the @once store - useful for testing and resetting state
+ */
+export declare function clearOnceStore(): void;
+/**
+ * Process @include and @partial directives
+ */
 export declare function processIncludes(template: string, context: Record<string, any>, filePath: string, options: StxOptions, dependencies: Set<string>): Promise<string>;
-declare const includeFilePath: unknown;
-declare const conditionFn: unknown;
-declare const includeFilePath: unknown;
-declare const conditionFn: unknown;
-declare const includeFilePath: unknown;
-declare const matchOffset: unknown;
-declare let pathArray: unknown;
-declare const varsFn: unknown;
-declare const includeFilePath: unknown;
-declare const processed: unknown;
-declare function resolvePath(includePath: string, partialsDir: string, filePath: string): string | null;
-declare let processedIncludes: (...args: any[]) => unknown;
-declare let matchOffset: unknown;
-declare const varsFn: unknown;
-declare const processedContent: unknown;
+/**
+ * Stack related functions for @push, @stack, @prepend directives
+ */
+/**
+ * Process @push and @prepend directives to collect content
+ */
 export declare function processStackPushDirectives(template: string, stacks: Record<string, string[]>): string;
-export declare function processStackReplacements(template: string, stacks: Record<string, string[]>): string;
+/**
+ * Process @stack directives by replacing them with their content
+ */
+export declare function processStackReplacements(template: string, stacks: Record<string, string[]>): string;
+// Cache for partials to avoid repeated file reads
+export declare const partialsCache: Map<string, string>;
+// Global store to track what has been included via @once
+export declare const onceStore: Set<string>;

package/dist/index.d.ts

@@ -1,24 +1,30 @@
-import { plugin } from 'bun-plugin-stx';
-
-export type { ComponentDoc, ComponentPropDoc, CustomDirective, DirectiveDoc, DocFormat, DocGeneratorConfig, HydrationConfig, I18nConfig, Island, Middleware, StreamingConfig, StreamRenderer, StxConfig, StxOptions, TemplateDoc, WebComponent, WebComponentConfig } from './types'
-
-export { createTranslateFilter, getTranslation, loadTranslation, processTranslateDirective } from './i18n'
-export { markdownDirectiveHandler, processMarkdownDirectives } from './markdown'
-export { createStreamRenderer, islandDirective, processSectionDirectives, registerStreamingDirectives, streamTemplate } from './streaming'
-export { buildWebComponents, webComponentDirectiveHandler } from './web-components'
-
-export * from './auth'
-export * from './caching'
-export * from './config'
-export * from './custom-directives'
-export * from './docs'
-export * from './expressions'
-export * from './forms'
-export * from './includes'
-export * from './loops'
-export * from './middleware'
-export * from './process'
-export * from './types'
-export * from './utils'
-
-export default plugin;
+export * from './a11y';
+export * from './analyzer';
+export * from './animation';
+export * from './assets';
+export * from './auth';
+export * from './caching';
+export * from './components';
+export * from './config';
+export * from './custom-directives';
+export * from './dev-server';
+export * from './docs';
+export * from './error-handling';
+export * from './expressions';
+export * from './formatter';
+export * from './forms';
+export * from './i18n';
+export * from './includes';
+export * from './init';
+export * from './loops';
+export * from './markdown';
+export * from './middleware';
+export * from './process';
+export * from './release';
+export * from './seo';
+export * from './serve';
+export * from './streaming';
+export * from './types';
+export * from './utils';
+export * from './web-components';
+export default {};

package/dist/init.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Initialize a new stx file with the specified name
+ */
+export declare function initFile(fileName?: string, options?: InitOptions): Promise<boolean>;
+// Interface for init options
+declare interface InitOptions {
+  force?: boolean
+  template?: string
+}

package/dist/js-ts.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Process JavaScript directives in templates
+ * Executes JavaScript code on the server and removes the code blocks from output
+ */
+export declare function processJsDirectives(template: string, context: Record<string, any>, filePath?: string): Promise<string>;
+/**
+ * Process TypeScript directives in templates
+ * Executes TypeScript code on the server and removes the code blocks from output
+ */
+export declare function processTsDirectives(template: string, context: Record<string, any>, filePath?: string): Promise<string>;

package/dist/loops.d.ts

@@ -1,3 +1,4 @@
-export declare function processLoops(template: string, context: Record<string, any>, filePath: string): string;
-declare const loopKeys: unknown;
-declare let whileFn: (...args: any[]) => unknown;
+/**
+ * Process loops (@foreach, @for, @while, @forelse)
+ */
+export declare function processLoops(template: string, context: Record<string, any>, filePath: string): string;

package/dist/markdown.d.ts

@@ -1,2 +1,10 @@
+/**
+ * Process markdown directives in templates
+ * Converts markdown content to HTML
+ */
 export declare function processMarkdownDirectives(template: string, context: Record<string, any>, filePath?: string): Promise<string>;
+/**
+ * Custom directive handler for markdown
+ * Can be registered as a custom directive
+ */
 export declare function markdownDirectiveHandler(content: string, params: string[], _context: Record<string, any>, _filePath: string): Promise<string>;

package/dist/method-spoofing.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generate a method spoofing input field
+ */
+export declare function methodField(method: string, fieldName?: string): string;
+/**
+ * Process @method directives in templates
+ */
+export declare function processMethodDirectives(template: string): string;
+/**
+ * Helper to get the original method from a request
+ * For middleware implementations
+ */
+export declare function getOriginalMethod(body: Record<string, any>, methodField?: string): string | null;

package/dist/middleware.d.ts

@@ -1,5 +1,13 @@
 import type { StxOptions } from './types';
-
+/**
+ * Process middleware registered in the application
+ */
 export declare function processMiddleware(template: string, context: Record<string, any>, filePath: string, options: StxOptions, timing: 'before' | 'after'): Promise<string>;
+/**
+ * Run pre-processing middleware
+ */
 export declare function runPreProcessingMiddleware(template: string, context: Record<string, any>, filePath: string, options: StxOptions): Promise<string>;
+/**
+ * Run post-processing middleware
+ */
 export declare function runPostProcessingMiddleware(template: string, context: Record<string, any>, filePath: string, options: StxOptions): Promise<string>;