@stacksjs/stx 0.2.0 → 0.2.3

package/dist/types.d.ts

@@ -1,315 +1 @@
-/**
- * Custom directive definition
- */
-export declare interface CustomDirective {
-  name: string
-  handler: CustomDirectiveHandler
-  hasEndTag?: boolean
-  description?: string
-}
-/**
- * Middleware definition
- */
-export declare interface Middleware {
-  name: string
-  handler: MiddlewareHandler
-  timing: 'before' | 'after'
-  description?: string
-}
-/**
- * Internationalization (i18n) configuration
- */
-export declare interface I18nConfig {
-  defaultLocale: string
-  locale: string
-  translationsDir: string
-  format: 'json' | 'yaml' | 'yml' | 'js'
-  fallbackToKey: boolean
-  cache: boolean
-}
-/**
- * Web component definition
- */
-export declare interface WebComponent {
-  name: string
-  tag: string
-  file: string
-  extends?: string
-  shadowDOM?: boolean
-  template?: boolean
-  styleSource?: string
-  attributes?: string[]
-  description?: string
-}
-/**
- * Web components configuration
- */
-export declare interface WebComponentConfig {
-  enabled: boolean
-  outputDir: string
-  components: WebComponent[]
-}
-/**
- * Component property documentation
- */
-export declare interface ComponentPropDoc {
-  name: string
-  type?: string
-  required?: boolean
-  default?: string
-  description?: string
-}
-/**
- * Component documentation
- */
-export declare interface ComponentDoc {
-  name: string
-  path: string
-  description?: string
-  props: ComponentPropDoc[]
-  example?: string
-  isWebComponent?: boolean
-  tag?: string
-}
-/**
- * Template documentation
- */
-export declare interface TemplateDoc {
-  name: string
-  path: string
-  description?: string
-  components?: string[]
-  directives?: string[]
-}
-/**
- * Directive documentation
- */
-export declare interface DirectiveDoc {
-  name: string
-  description?: string
-  hasEndTag: boolean
-  example?: string
-}
-/**
- * Documentation generator configuration
- */
-export declare interface DocGeneratorConfig {
-  enabled: boolean
-  outputDir: string
-  format: DocFormat
-  components: boolean
-  templates: boolean
-  directives: boolean
-  extraContent?: string
-  template?: string
-}
-/**
- * Streaming configuration
- */
-export declare interface StreamingConfig {
-  enabled: boolean
-  bufferSize: number
-  strategy: 'auto' | 'manual' | 'sections'
-  timeout: number
-}
-/**
- * Stream renderer for progressive loading
- */
-export declare interface StreamRenderer {
-  renderShell: (data?: Record<string, any>) => Promise<string>
-  renderSection: (section: string, data?: Record<string, any>) => Promise<string>
-  getSections: () => string[]
-  getTemplate: () => string
-}
-/**
- * Hydration configuration
- */
-export declare interface HydrationConfig {
-  enabled: boolean
-  mode: 'progressive' | 'islands'
-  clientEntry: string
-  autoMarkers: boolean
-  preload: 'none' | 'eager' | 'lazy'
-}
-/**
- * Island definition for partial hydration
- */
-export declare interface Island {
-  id: string
-  component: string
-  props?: Record<string, any>
-  priority?: 'eager' | 'lazy'
-  shadowDOM?: boolean
-}
-/**
- * Accessibility configuration
- */
-export declare interface A11yConfig {
-  enabled: boolean
-  addSrOnlyStyles: boolean
-  level: 'AA' | 'AAA'
-  ignoreChecks?: string[]
-  autoFix: boolean
-}
-/**
- * SEO OpenGraph configuration
- */
-export declare interface OpenGraphConfig {
-  type?: string
-  title?: string
-  description?: string
-  url?: string
-  image?: string
-  imageAlt?: string
-  imageWidth?: number
-  imageHeight?: number
-  siteName?: string
-}
-/**
- * SEO Twitter card configuration
- */
-export declare interface TwitterConfig {
-  card?: 'summary' | 'summary_large_image' | 'app' | 'player'
-  title?: string
-  description?: string
-  image?: string
-  site?: string
-  creator?: string
-}
-/**
- * SEO configuration
- */
-export declare interface SeoConfig {
-  title?: string
-  description?: string
-  keywords?: string[] | string
-  robots?: string
-  canonical?: string
-  openGraph?: OpenGraphConfig
-  twitter?: TwitterConfig
-  structuredData?: Record<string, any>
-}
-/**
- * SEO features configuration
- */
-export declare interface SeoFeatureConfig {
-  enabled: boolean
-  defaultConfig?: SeoConfig
-  socialPreview?: boolean
-  defaultImage?: string
-}
-/**
- * Animation configuration
- */
-export declare interface AnimationConfig {
-  enabled: boolean
-  defaultDuration: number
-  defaultEase: string
-  respectMotionPreferences: boolean
-  staggerDelay: number
-}
-/**
- * Syntax highlighting configuration
- */
-export declare interface SyntaxHighlightingConfig {
-  enabled: boolean
-  serverSide: boolean
-  defaultTheme: SyntaxHighlightTheme
-  highlightUnknownLanguages: boolean
-  additionalThemes?: SyntaxHighlightTheme[]
-}
-/**
- * Markdown configuration
- */
-export declare interface MarkdownConfig {
-  enabled: boolean
-  dir?: string
-  syntaxHighlighting?: Partial<SyntaxHighlightingConfig>
-}
-/**
- * stx configuration options
- */
-export declare interface StxConfig {
-  templatesDir?: string
-  defaultTitle?: string
-  defaultDescription?: string
-  defaultImage?: string
-  cache?: boolean
-  cacheDir?: string
-  cacheVersion?: string
-  enabled: boolean
-  partialsDir: string
-  componentsDir: string
-  debug: boolean
-  cachePath: string
-  customDirectives?: CustomDirective[]
-  middleware?: Middleware[]
-  i18n?: Partial<I18nConfig>
-  webComponents?: Partial<WebComponentConfig>
-  docs?: Partial<DocGeneratorConfig>
-  streaming?: Partial<StreamingConfig>
-  hydration?: Partial<HydrationConfig>
-  a11y?: Partial<A11yConfig>
-  seo?: Partial<SeoFeatureConfig>
-  animation?: Partial<AnimationConfig>
-  skipDefaultSeoTags?: boolean
-  markdown?: Partial<MarkdownConfig>
-}
-/**
- * stx Config
- */
-/**
- * Custom directive handler function
- */
-export type CustomDirectiveHandler = (
-  content: string,
-  params: string[],
-  context: Record<string, any>,
-  filePath: string
-) => string | Promise<string>
-/**
- * Middleware handler function
- */
-export type MiddlewareHandler = (
-  template: string,
-  context: Record<string, any>,
-  filePath: string,
-  options: StxOptions
-) => string | Promise<string>
-/**
- * Documentation format options
- */
-export type DocFormat = 'markdown' | 'html' | 'json'
-/**
- * Available syntax highlighting themes
- */
-export type SyntaxHighlightTheme = | 'css-variables'
-  | 'dark-plus'
-  | 'dracula'
-  | 'dracula-soft'
-  | 'github-dark'
-  | 'github-dark-dimmed'
-  | 'github-light'
-  | 'hc_light'
-  | 'light-plus'
-  | 'material-theme'
-  | 'material-theme-darker'
-  | 'material-theme-lighter'
-  | 'material-theme-ocean'
-  | 'material-theme-palenight'
-  | 'min-dark'
-  | 'min-light'
-  | 'monokai'
-  | 'nord'
-  | 'one-dark-pro'
-  | 'poimandres'
-  | 'rose-pine'
-  | 'rose-pine-dawn'
-  | 'rose-pine-moon'
-  | 'slack-dark'
-  | 'slack-ochin'
-  | 'solarized-dark'
-  | 'solarized-light'
-  | 'vitesse-dark'
-  | 'vitesse-light'
-export type StxOptions = Partial<StxConfig>
+export * from './types/index';

package/dist/typescript-templates.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Parse a TypeScript type annotation string into a TSType structure.
+ *
+ * @example
+ * parseTypeAnnotation('string') // { kind: 'primitive', value: 'string' }
+ * parseTypeAnnotation('string[]') // { kind: 'array', elementType: { kind: 'primitive', value: 'string' } }
+ * parseTypeAnnotation('{ name: string }') // { kind: 'object', properties: { name: { type: ..., optional: false } } }
+ */
+export declare function parseTypeAnnotation(typeStr: string): TSType;
+/**
+ * Extract type definitions from a template's @types block.
+ *
+ * @example
+ * ```typescript
+ * const result = extractTypesFromTemplate(`
+ *   @types
+ *   interface PageContext {
+ *     title: string
+ *   }
+ *   @endtypes
+ *   <h1>{{ title }}</h1>
+ * `)
+ * // result.interfaces[0].name === 'PageContext'
+ * ```
+ */
+export declare function extractTypesFromTemplate(template: string): TypeExtractionResult;
+/**
+ * Create a type context from extracted types and runtime context.
+ */
+export declare function createTypeContext(extracted: TypeExtractionResult, runtimeContext?: Record<string, unknown>): TemplateTypeContext;
+/**
+ * Infer a TSType from a runtime value.
+ */
+export declare function inferTypeFromValue(value: unknown): TSType;
+/**
+ * Type-check an expression against the type context.
+ *
+ * @returns The inferred type of the expression, or an error
+ */
+export declare function typeCheckExpression(expression: string, context: TemplateTypeContext): TSType | TypeCheckError;
+/**
+ * Validate all expressions in a template.
+ */
+export declare function validateTemplateTypes(template: string, context: TemplateTypeContext): TypeCheckError[];
+/**
+ * Generate TypeScript definition file for a template.
+ *
+ * This creates a .d.ts file that provides type information for IDE support.
+ */
+export declare function generateTypeDefinitions(templatePath: string, extracted: TypeExtractionResult): GeneratedTypes;
+/**
+ * Convert a TSType back to a TypeScript string representation.
+ */
+export declare function typeToString(type: TSType): string;
+/**
+ * Process @types directive - extracts and removes type definitions.
+ */
+export declare function processTypesDirective(template: string): {
+  template: string
+  types: TypeExtractionResult
+};
+/**
+ * Compile-time type check a template.
+ *
+ * @returns Array of errors/warnings, empty if valid
+ */
+export declare function compileTimeTypeCheck(template: string, runtimeContext?: Record<string, unknown>): { errors: TypeCheckError[], warnings: TypeCheckWarning[] };
+/** TypeScript type representation */
+export declare interface TSType {
+  kind: 'primitive' | 'array' | 'object' | 'union' | 'intersection' | 'literal' | 'function' | 'generic' | 'reference'
+  value?: TSPrimitiveType | string
+  elementType?: TSType
+  properties?: Record<string, TSTypeProperty>
+  types?: TSType[]
+  literalValue?: string | number | boolean
+  parameters?: TSFunctionParam[]
+  returnType?: TSType
+  typeArguments?: TSType[]
+  optional?: boolean
+}
+/** Object property with type */
+export declare interface TSTypeProperty {
+  type: TSType
+  optional: boolean
+  readonly: boolean
+  description?: string
+}
+/** Function parameter */
+export declare interface TSFunctionParam {
+  name: string
+  type: TSType
+  optional: boolean
+  rest: boolean
+}
+/** Interface definition */
+export declare interface TSInterface {
+  name: string
+  properties: Record<string, TSTypeProperty>
+  extends?: string[]
+  description?: string
+}
+/** Type alias definition */
+export declare interface TSTypeAlias {
+  name: string
+  type: TSType
+  description?: string
+}
+/** Template type context */
+export declare interface TemplateTypeContext {
+  interfaces: Map<string, TSInterface>
+  typeAliases: Map<string, TSTypeAlias>
+  variables: Map<string, TSType>
+  errors: TypeCheckError[]
+  warnings: TypeCheckWarning[]
+}
+/** Type check error */
+export declare interface TypeCheckError {
+  message: string
+  line?: number
+  column?: number
+  expression?: string
+  expectedType?: string
+  actualType?: string
+}
+/** Type check warning */
+export declare interface TypeCheckWarning {
+  message: string
+  line?: number
+  column?: number
+  suggestion?: string
+}
+/** Type extraction result */
+export declare interface TypeExtractionResult {
+  interfaces: TSInterface[]
+  typeAliases: TSTypeAlias[]
+  contextType?: TSInterface
+  errors: string[]
+}
+/** Generated type definition file content */
+export declare interface GeneratedTypes {
+  content: string
+  filename: string
+}
+/**
+ * TypeScript-First Templates Module
+ *
+ * Provides compile-time type checking and TypeScript support for stx templates.
+ *
+ * ## Features
+ *
+ * 1. **Type-Safe Context** - Define typed interfaces for template context
+ * 2. **Compile-Time Checking** - Validate expressions against context types
+ * 3. **Type Inference** - Infer types from script blocks
+ * 4. **Type Generation** - Generate TypeScript definitions from templates
+ * 5. **IDE Support** - Enable autocomplete and type hints in editors
+ *
+ * ## Usage
+ *
+ * ```html
+ * <!-- Define context type at top of template -->
+ * @types
+ * interface PageContext {
+ *   title: string
+ *   items: Array<{ id: number; name: string }>
+ *   user?: { name: string; role: 'admin' | 'user' }
+ * }
+ * @endtypes
+ *
+ * <h1>{{ title }}</h1>
+ * @foreach(items as item)
+ *   <p>{{ item.name }}</p>  <!-- Type-checked! -->
+ * @endforeach
+ * ```
+ *
+ * @module typescript-templates
+ */
+/** Supported TypeScript primitive types */
+export type TSPrimitiveType = 'string' | 'number' | 'boolean' | 'null' | 'undefined' | 'any' | 'unknown' | 'never' | 'void'

package/dist/utils.d.ts

@@ -1,16 +1,30 @@
 import type { StxOptions } from './types';
+export type {
+  TemplateValidationError,
+  TemplateValidationResult,
+} from './validator';
+/**
+ * Check if script should be treated as plain JavaScript (opt-out from TypeScript)
+ * By default ALL scripts are TypeScript. Use <script js> or <script lang="js"> to opt-out.
+ */
+export declare function isJavaScriptScript(attrs: string): boolean;
+/**
+ * Check if script should be transpiled as TypeScript
+ * Default: ALL scripts are TypeScript unless explicitly marked as JS
+ */
+export declare function shouldTranspileTypeScript(attrs: string): boolean;
+/**
+ * Transpile TypeScript code to JavaScript using Bun (sync version)
+ */
+export declare function transpileTypeScript(code: string): string;
 /**
  * Shared function to render a component with props and slot content
  */
-export declare function renderComponent(componentPath: string, props: Record<string, any>, slotContent: string, componentsDir: string, parentContext: Record<string, any>, parentFilePath: string, options: StxOptions, processedComponents?: Set<string> | undefined, dependencies: Set<string>): Promise<string>;
+export declare function renderComponentWithSlot(componentPath: string, props: Record<string, unknown>, slotContent: string, componentsDir: string, parentContext: Record<string, unknown>, parentFilePath: string, options: StxOptions, processedComponents?: Set<string> | undefined, dependencies: Set<string>): Promise<string>;
 /**
  * Check if a file exists
  */
 export declare function fileExists(filePath: string): Promise<boolean>;
-/**
- * Extract variables from script content
- */
-export declare function extractVariables(scriptContent: string, context: Record<string, any>, filePath: string): Promise<void>;
 /**
  * Resolve a template path based on the current file path
  */
@@ -24,4 +38,36 @@ export declare function resolveTemplatePath(templatePath: string, currentFilePat
  * @returns Line number and context information
  */
 export declare function getSourceLineInfo(template: string, errorPosition?: number, errorPattern?: string): { lineNumber: number, lineContent: string, context: string };
-export declare function createDetailedErrorMessage(errorType: string, errorMessage: string, filePath: string, template: string, errorPosition?: number, errorPattern?: string): string;
+/**
+ * Create a descriptive error message with line information
+ * @param errorType Type of error (e.g., "Expression", "Directive")
+ * @param errorMessage The base error message
+ * @param filePath The file where the error occurred
+ * @param template The template content
+ * @param errorPosition The position of the error (if known)
+ * @param errorPattern A pattern to locate the error (fallback)
+ * @returns A formatted error message
+ */
+export declare function createDetailedErrorMessage(errorType: string, errorMessage: string, filePath: string, template: string, errorPosition?: number, errorPattern?: string): string;
+/**
+ * Clear the component cache
+ * Useful for development or testing
+ */
+export declare function clearComponentCache(): void;
+/**
+ * Get component cache statistics
+ */
+export declare function getComponentCacheStats(): { size: number, maxSize: number };
+export {
+  extractDirectiveNames,
+  getPositionInfo,
+  hasDirectives,
+  validateDirective,
+  validateTemplate,
+} from './validator';
+export {
+  convertToCommonJS,
+  extractScriptFromTemplate,
+  extractVariables,
+  hasVariables,
+} from './variable-extractor';

package/dist/validator.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Validate a template before processing
+ *
+ * Checks for common syntax errors and structural issues:
+ * - Unclosed directive blocks (@if without @endif)
+ * - Unclosed expression brackets
+ * - Invalid directive syntax
+ * - Nested quote issues
+ * - Security-related patterns
+ *
+ * @param template - The template string to validate
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validateTemplate(templateString)
+ * if (!result.valid) {
+ *   console.error('Template errors:', result.errors)
+ * }
+ * ```
+ */
+export declare function validateTemplate(template: string): TemplateValidationResult;
+/**
+ * Get line and column information for a position in the template
+ *
+ * @param template - The template string
+ * @param position - Character position
+ * @returns Line and column numbers (1-indexed)
+ */
+export declare function getPositionInfo(template: string, position: number): { line: number, column: number };
+/**
+ * Validate a specific directive's syntax
+ *
+ * @param directiveName - Name of the directive (without @)
+ * @param content - Content between directive tags
+ * @param params - Parameters passed to the directive
+ * @returns Validation errors, if any
+ */
+export declare function validateDirective(directiveName: string, content: string, params: string[]): TemplateValidationError[];
+/**
+ * Check if a template has any directives
+ *
+ * @param template - The template string
+ * @returns Whether the template contains any stx directives
+ */
+export declare function hasDirectives(template: string): boolean;
+/**
+ * Extract all directive names used in a template
+ *
+ * @param template - The template string
+ * @returns Array of directive names (without @ prefix)
+ */
+export declare function extractDirectiveNames(template: string): string[];
+/**
+ * Template Validation
+ *
+ * Provides validation utilities for stx templates before processing.
+ * Checks for common syntax errors, structural issues, and potential security problems.
+ */
+/**
+ * Template validation error
+ */
+export declare interface TemplateValidationError {
+  type: 'syntax' | 'directive' | 'expression' | 'structure'
+  message: string
+  line?: number
+  column?: number
+  suggestion?: string
+}
+/**
+ * Template validation result
+ */
+export declare interface TemplateValidationResult {
+  valid: boolean
+  errors: TemplateValidationError[]
+  warnings: TemplateValidationError[]
+}

package/dist/variable-extractor.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Strip TypeScript-specific syntax to make it executable as JavaScript
+ *
+ * @param scriptContent - TypeScript/JavaScript code
+ * @returns JavaScript code with TypeScript syntax stripped
+ */
+export declare function stripTypeScript(scriptContent: string): string;
+/**
+ * Extract variables from script content and add them to context
+ *
+ * @param scriptContent - The JavaScript/TypeScript code from a <script> tag
+ * @param context - The context object to populate with extracted variables
+ * @param filePath - Path to the file (for error messages)
+ */
+export declare function extractVariables(scriptContent: string, context: Record<string, unknown>, filePath: string): Promise<void>;
+/**
+ * Convert ES module syntax to CommonJS
+ *
+ * @param scriptContent - ES module style script content
+ * @returns CommonJS compatible script
+ */
+export declare function convertToCommonJS(scriptContent: string): string;
+/**
+ * Extract script content from an HTML template
+ *
+ * @param template - The template string
+ * @returns Object with script content and template without script tags
+ */
+export declare function extractScriptFromTemplate(template: string): {
+  scriptContent: string
+  templateWithoutScript: string
+};
+/**
+ * Check if script content has any variables to extract
+ *
+ * @param scriptContent - The script content
+ * @returns Whether variables are present
+ */
+export declare function hasVariables(scriptContent: string): boolean;