@stacksjs/stx 0.1.16 → 0.2.3

package/dist/a11y.d.ts

@@ -1,20 +1,97 @@
 import type { CustomDirective, StxOptions } from './types';
 /**
- * Process accessibility directives
+ * Process accessibility directives.
+ * Handles @a11y hints, @screenReader content, and @ariaDescribe.
  */
-export declare function processA11yDirectives(template: string, context: Record<string, any>, filePath: string, options: StxOptions): string;
+export declare function processA11yDirectives(template: string, _context: Record<string, any>, _filePath: string, _options: StxOptions): string;
 /**
- * Create the screen reader only style
+ * Create the screen reader only CSS style.
+ * Add this to your stylesheet or inject via `<style>` tag.
  */
 export declare function getScreenReaderOnlyStyle(): string;
 /**
- * Automatically check template for accessibility issues
+ * Check if DOM environment is available.
+ * Useful for determining which accessibility checking mode will be used.
+ *
+ * @returns true if DOM APIs are available (happy-dom, jsdom, browser)
+ *
+ * @example
+ * ```typescript
+ * if (hasDOMSupport()) {
+ *   console.log('Using full DOM-based a11y checking')
+ * } else {
+ *   console.log('Using regex-based a11y checking (limited)')
+ * }
+ * ```
+ */
+export declare function hasDOMSupport(): boolean;
+/**
+ * Automatically check template for accessibility issues.
+ *
+ * This function works in both DOM and non-DOM environments:
+ * - With DOM (happy-dom/jsdom): Full accessibility checking with element traversal
+ * - Without DOM: Regex-based checking for common issues
+ *
+ * @param html - HTML content to check
+ * @param filePath - File path for error reporting
+ * @returns Array of accessibility violations found
+ *
+ * @example
+ * ```typescript
+ * const violations = await checkA11y('<img src="photo.jpg">', 'page.html')
+ * // violations[0].type === 'missing-alt'
+ * ```
  */
 export declare function checkA11y(html: string, filePath: string): Promise<A11yViolation[]>;
 /**
- * Scan a directory of stx files for accessibility issues
+ * Scan a directory of stx files for accessibility issues.
+ * Returns a map of file paths to their violations.
  */
 export declare function scanA11yIssues(directory: string, options?: { recursive?: boolean, ignorePaths?: string[] }): Promise<Record<string, A11yViolation[]>>;
+/**
+ * Auto-fix accessibility issues in HTML content.
+ *
+ * This function attempts to automatically fix common accessibility issues.
+ * Note that some fixes may require manual review to ensure they make sense
+ * in context (e.g., alt text should be descriptive, not just present).
+ *
+ * @param html - HTML content to fix
+ * @param config - Auto-fix configuration
+ * @returns Fixed HTML and details of changes made
+ *
+ * @example
+ * const result = autoFixA11y('<img src="photo.jpg">')
+ * // result.fixed = '<img src="photo.jpg" alt="">'
+ * // result.fixCount = 1
+ */
+export declare function autoFixA11y(html: string, config?: A11yAutoFixConfig): A11yFixResult;
+/**
+ * Auto-fix accessibility issues in a file and optionally write back.
+ *
+ * @param filePath - Path to the file to fix
+ * @param config - Auto-fix configuration
+ * @param writeBack - Whether to write the fixed content back to the file
+ * @returns Fix result
+ */
+export declare function autoFixA11yFile(filePath: string, config?: A11yAutoFixConfig, writeBack?: any): Promise<A11yFixResult>;
+/**
+ * Auto-fix accessibility issues in a directory of files.
+ *
+ * @param directory - Directory to scan
+ * @param config - Auto-fix configuration
+ * @param options - Scan options
+ * @param options.recursive - Whether to scan recursively (default: true)
+ * @param options.ignorePaths - Paths to ignore
+ * @param options.writeBack - Whether to write fixes back to files (default: false)
+ * @param options.extensions - File extensions to process (default: ['.stx', '.html', '.htm'])
+ * @returns Map of file paths to fix results
+ */
+export declare function autoFixA11yDirectory(directory: string, config?: A11yAutoFixConfig, options?: {
+    recursive?: boolean
+    ignorePaths?: string[]
+    writeBack?: boolean
+    extensions?: string[]
+  }): Promise<Record<string, A11yFixResult>>;
 /**
  * Register all a11y directives
  */
@@ -37,4 +114,31 @@ export declare interface A11yViolation {
   impact: 'critical' | 'serious' | 'moderate' | 'minor'
   help: string
   helpUrl?: string
+}
+/**
+ * Auto-fix result
+ */
+export declare interface A11yFixResult {
+  original: string
+  fixed: string
+  fixCount: number
+  fixes: Array<{
+    type: string
+    description: string
+    before: string
+    after: string
+  }>
+}
+/**
+ * Auto-fix configuration
+ */
+export declare interface A11yAutoFixConfig {
+  fixMissingAlt?: boolean
+  fixMissingLabels?: boolean
+  fixMissingFormLabels?: boolean
+  fixTableHeaders?: boolean
+  fixMissingLang?: boolean
+  fixPositiveTabindex?: boolean
+  fixButtonFocusable?: boolean
+  defaultLang?: string
 }

package/dist/analytics.d.ts

@@ -0,0 +1,40 @@
+import type { CustomDirective, StxOptions } from './types';
+/**
+ * Analytics Module
+ *
+ * Provides automatic analytics script injection for various providers:
+ * - Fathom Analytics (privacy-focused)
+ * - Google Analytics (GA4)
+ * - Plausible Analytics (privacy-focused, open source)
+ * - Self-hosted analytics (using dynamodb-tooling)
+ * - Custom analytics scripts
+ *
+ * ## Configuration
+ *
+ * Analytics can be configured in `stx.config.ts`:
+ * ```typescript
+ * export default {
+ *   analytics: {
+ *     enabled: true,
+ *     driver: 'fathom',
+ *     fathom: {
+ *       siteId: 'ABCDEFGH',
+ *       honorDnt: true,
+ *     }
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Generate analytics tracking script based on configuration
+ */
+export declare function generateAnalyticsScript(options: StxOptions): string;
+/**
+ * Inject analytics script into HTML
+ * Scripts are injected just before </head> for optimal loading
+ */
+export declare function injectAnalytics(html: string, options: StxOptions): string;
+/**
+ * Custom @analytics directive for explicit placement
+ */
+export declare const analyticsDirective: CustomDirective;

package/dist/animation.d.ts

@@ -1,8 +1,25 @@
-import type { StxOptions } from './types';
+import type { CustomDirective, StxOptions } from './types';
 /**
  * Process animation directives in the template
  */
 export declare function processAnimationDirectives(template: string, context: Record<string, any>, filePath: string, options: StxOptions): string;
+/**
+ * Create an animation timeline for coordinated animations
+ */
+export declare function createAnimationTimeline(entries: TimelineEntry[]): string;
+/**
+ * Generate CSS for a custom animation
+ */
+export declare function generateAnimationCSS(name: string, keyframes: Keyframe[], options: KeyframeAnimationOptions): string;
+/**
+ * Parse animation shorthand string
+ * Format: "duration [delay] [easing] [iterations] [direction] [fill]"
+ */
+export declare function parseAnimationShorthand(shorthand: string): KeyframeAnimationOptions;
+/**
+ * Generate client-side animation runtime
+ */
+export declare function generateAnimationRuntime(): string;
 /**
  * Register animation directives
  */
@@ -32,6 +49,79 @@ export declare const animationGroupDirective: CustomDirective;
  * Motion preferences directive for controlling animation preferences
  */
 export declare const motionDirective: CustomDirective;
+/** Preset spring configurations */
+export declare const SPRING_PRESETS: {
+  default: {
+  stiffness: 100;
+  damping: 10;
+  mass: 1
+};
+  gentle: {
+  stiffness: 120;
+  damping: 14;
+  mass: 1
+};
+  wobbly: {
+  stiffness: 180;
+  damping: 12;
+  mass: 1
+};
+  stiff: {
+  stiffness: 210;
+  damping: 20;
+  mass: 1
+};
+  slow: {
+  stiffness: 280;
+  damping: 60;
+  mass: 1
+};
+  molasses: {
+  stiffness: 280;
+  damping: 120;
+  mass: 1
+}
+};
+/**
+ * @keyframe directive for custom keyframe animations
+ */
+export declare const keyframeDirective: CustomDirective;
+/**
+ * @stagger directive for staggered child animations
+ */
+export declare const staggerDirective: CustomDirective;
+/**
+ * @spring directive for spring physics animations
+ */
+export declare const springDirective: CustomDirective;
+/** Keyframe definition */
+export declare interface Keyframe {
+  offset?: number
+  properties: Record<string, string | number>
+  easing?: string
+}
+/** Animation timeline entry */
+export declare interface TimelineEntry {
+  selector: string
+  keyframes: Keyframe[]
+  options: KeyframeAnimationOptions
+}
+/** Keyframe animation options */
+export declare interface KeyframeAnimationOptions {
+  duration: number
+  delay?: number
+  easing?: string
+  iterations?: number | 'infinite'
+  direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse'
+  fill?: 'none' | 'forwards' | 'backwards' | 'both'
+}
+/** Spring animation config */
+export declare interface SpringConfig {
+  stiffness: number
+  damping: number
+  mass: number
+  velocity?: number
+}
 /**
  * Available transition types that can be used with @transition directive
  */

package/dist/app.d.ts

@@ -0,0 +1,51 @@
+import type { CustomDirective } from './types';
+/**
+ * Create an stx application instance.
+ *
+ * ```ts
+ * import { createApp } from '@stacksjs/stx'
+ *
+ * const app = createApp()
+ *
+ * app.use(myPlugin)
+ * app.provide('theme', 'dark')
+ * app.component('MyButton', MyButton)
+ * app.mount('#app')
+ * ```
+ *
+ * @param rootComponent - Optional root component definition
+ * @param rootProps - Optional props for the root component
+ */
+export declare function createApp(_rootComponent?: any, _rootProps?: Record<string, any>): StxApp;
+/** A Vue-compatible plugin with install method */
+export declare interface StxAppPlugin {
+  install: (app: StxApp, ...options: any[]) => void
+}
+/** The stx application instance */
+export declare interface StxApp {
+  use(plugin: StxPluginInput, ...options: any[]): StxApp
+  provide(key: string | symbol, value: T): StxApp
+  component(name: string, definition?: any): StxApp | any
+  directive(name: string, definition?: CustomDirective | Record<string, any>): StxApp | any
+  mount(rootContainer?: string | Element): StxApp
+  unmount(): void
+  config: StxAppConfig
+  _components: Map<string, any>
+  _directives: Map<string, any>
+  _installedPlugins: Set<StxPluginInput>
+}
+/** Application configuration */
+export declare interface StxAppConfig {
+  errorHandler?: (error: Error, instance: any, info: string) => void
+  warnHandler?: (msg: string, instance: any, trace: string) => void
+  globalProperties: Record<string, any>
+  performance: boolean
+  compilerOptions: {
+    /** Custom element tag pattern */
+    isCustomElement?: (tag: string) => boolean
+    /** Whitespace handling */
+    whitespace?: 'condense' | 'preserve'
+  }
+}
+/** Plugin can be an object with install() or a plain function */
+export type StxPluginInput = StxAppPlugin | ((app: StxApp, ...options: any[]) => void)

package/dist/ast.d.ts

@@ -0,0 +1,286 @@
+import type { Position } from './source-maps';
+// =============================================================================
+// Node Guards
+// =============================================================================
+export declare function isDocumentNode(node: ASTNode): node is DocumentNode;
+export declare function isTextNode(node: ASTNode): node is TextNode;
+export declare function isExpressionNode(node: ASTNode): node is ExpressionNode;
+export declare function isDirectiveNode(node: ASTNode): node is DirectiveNode;
+export declare function isComponentNode(node: ASTNode): node is ComponentNode;
+export declare function isElementNode(node: ASTNode): node is ElementNode;
+export declare function isAttributeNode(node: ASTNode): node is AttributeNode;
+export declare function isCommentNode(node: ASTNode): node is CommentNode;
+export declare function isScriptNode(node: ASTNode): node is ScriptNode;
+export declare function isStyleNode(node: ASTNode): node is StyleNode;
+/**
+ * Create a document node
+ */
+export declare function createDocument(children?: ASTNode[], loc?: SourceLocation): DocumentNode;
+/**
+ * Create a text node
+ */
+export declare function createText(value: string, loc?: SourceLocation): TextNode;
+/**
+ * Create an expression node
+ */
+export declare function createExpression(expression: string, escaped?: boolean, loc?: SourceLocation): ExpressionNode;
+/**
+ * Create a directive node
+ */
+export declare function createDirective(name: string, params?: string | null, body?: ASTNode[] | null, loc?: SourceLocation): DirectiveNode;
+/**
+ * Create a component node
+ */
+export declare function createComponent(name: string, attributes?: AttributeNode[], children?: ASTNode[], selfClosing?: boolean, loc?: SourceLocation): ComponentNode;
+/**
+ * Create an element node
+ */
+export declare function createElement(tag: string, attributes?: AttributeNode[], children?: ASTNode[], loc?: SourceLocation): ElementNode;
+/**
+ * Create an attribute node
+ */
+export declare function createAttribute(name: string, value?: string | ExpressionNode | null, loc?: SourceLocation): AttributeNode;
+/**
+ * Create a comment node
+ */
+export declare function createComment(value: string, style?: 'html' | 'stx', loc?: SourceLocation): CommentNode;
+/**
+ * Create a script node
+ */
+export declare function createScript(content: string, attributes?: AttributeNode[], loc?: SourceLocation): ScriptNode;
+/**
+ * Create a style node
+ */
+export declare function createStyle(content: string, attributes?: AttributeNode[], scoped?: boolean, loc?: SourceLocation): StyleNode;
+/**
+ * Walk the AST and call visitor callbacks
+ */
+export declare function walkAST(node: ASTNode, visitor: ASTVisitor, parent?: ASTNode | null): void;
+/**
+ * Get child nodes of a node
+ */
+export declare function getChildren(node: ASTNode): ASTNode[];
+/**
+ * Clone an AST node deeply
+ */
+export declare function cloneNode<T extends ASTNode>(node: T): T;
+/**
+ * Replace a node in the AST
+ */
+export declare function replaceNode(root: DocumentNode, target: ASTNode, replacement: ASTNode | ASTNode[]): void;
+/**
+ * Remove a node from the AST
+ */
+export declare function removeNode(root: DocumentNode, target: ASTNode): void;
+/**
+ * Find all nodes matching a predicate
+ */
+export declare function findNodes(root: ASTNode, predicate: (node: ASTNode) => boolean): ASTNode[];
+/**
+ * Find all nodes of a specific type
+ */
+export declare function findNodesByType<T extends ASTNode['type']>(root: ASTNode, type: T): Extract<ASTNode, { type: T }>[];
+/**
+ * Find all directives by name
+ */
+export declare function findDirectives(root: ASTNode, name: string): DirectiveNode[];
+/**
+ * Find all components by name
+ */
+export declare function findComponents(root: ASTNode, name: string): ComponentNode[];
+/**
+ * Find all elements by tag name
+ */
+export declare function findElements(root: ASTNode, tag: string): ElementNode[];
+/**
+ * Get all expression nodes in the AST
+ */
+export declare function getExpressions(root: ASTNode): ExpressionNode[];
+/**
+ * Get all directive names used in the template
+ */
+export declare function getDirectiveNames(root: ASTNode): Set<string>;
+/**
+ * Get all component names used in the template
+ */
+export declare function getComponentNames(root: ASTNode): Set<string>;
+/**
+ * Generate code from AST
+ */
+export declare function generateCode(node: ASTNode): string;
+/**
+ * Source location in template
+ */
+export declare interface SourceLocation {
+  start: Position
+  end: Position
+  source?: string
+}
+/**
+ * Base interface for all AST nodes
+ */
+export declare interface BaseNode {
+  type: string
+  loc?: SourceLocation
+  parent?: ASTNode
+}
+/**
+ * Document root node
+ */
+export declare interface DocumentNode extends BaseNode {
+  type: 'Document'
+  children: ASTNode[]
+}
+/**
+ * Plain text content
+ */
+export declare interface TextNode extends BaseNode {
+  type: 'Text'
+  value: string
+}
+/**
+ * Expression interpolation: {{ expr }} or {!! expr !!}
+ */
+export declare interface ExpressionNode extends BaseNode {
+  type: 'Expression'
+  expression: string
+  escaped: boolean
+  raw: string
+}
+/**
+ * Directive: @name(params) ... @endname
+ */
+export declare interface DirectiveNode extends BaseNode {
+  type: 'Directive'
+  name: string
+  params: string | null
+  body: ASTNode[] | null
+  selfClosing: boolean
+  raw: string
+}
+/**
+ * Component: <ComponentName attr="value">...</ComponentName>
+ */
+export declare interface ComponentNode extends BaseNode {
+  type: 'Component'
+  name: string
+  attributes: AttributeNode[]
+  children: ASTNode[]
+  selfClosing: boolean
+}
+/**
+ * HTML Element: <tag attr="value">...</tag>
+ */
+export declare interface ElementNode extends BaseNode {
+  type: 'Element'
+  tag: string
+  attributes: AttributeNode[]
+  children: ASTNode[]
+  selfClosing: boolean
+  void: boolean
+}
+/**
+ * Attribute on element or component
+ */
+export declare interface AttributeNode extends BaseNode {
+  type: 'Attribute'
+  name: string
+  value: string | ExpressionNode | null
+  dynamic: boolean
+}
+/**
+ * Comment: <!-- comment --> or {{-- comment --}}
+ */
+export declare interface CommentNode extends BaseNode {
+  type: 'Comment'
+  value: string
+  style: 'html' | 'stx'
+}
+/**
+ * Script block: <script>...</script>
+ */
+export declare interface ScriptNode extends BaseNode {
+  type: 'Script'
+  content: string
+  attributes: AttributeNode[]
+}
+/**
+ * Style block: <style>...</style>
+ */
+export declare interface StyleNode extends BaseNode {
+  type: 'Style'
+  content: string
+  attributes: AttributeNode[]
+  scoped: boolean
+}
+/**
+ * Visitor callbacks for AST traversal
+ */
+export declare interface ASTVisitor {
+  enter?: (node: ASTNode, parent: ASTNode | null) => void | false
+  leave?: (node: ASTNode, parent: ASTNode | null) => void
+  Document?: { enter?: (node: DocumentNode) => void | false, leave?: (node: DocumentNode) => void }
+  Text?: { enter?: (node: TextNode) => void | false, leave?: (node: TextNode) => void }
+  Expression?: { enter?: (node: ExpressionNode) => void | false, leave?: (node: ExpressionNode) => void }
+  Directive?: { enter?: (node: DirectiveNode) => void | false, leave?: (node: DirectiveNode) => void }
+  Component?: { enter?: (node: ComponentNode) => void | false, leave?: (node: ComponentNode) => void }
+  Element?: { enter?: (node: ElementNode) => void | false, leave?: (node: ElementNode) => void }
+  Attribute?: { enter?: (node: AttributeNode) => void | false, leave?: (node: AttributeNode) => void }
+  Comment?: { enter?: (node: CommentNode) => void | false, leave?: (node: CommentNode) => void }
+  Script?: { enter?: (node: ScriptNode) => void | false, leave?: (node: ScriptNode) => void }
+  Style?: { enter?: (node: StyleNode) => void | false, leave?: (node: StyleNode) => void }
+}
+/**
+ * Union of all AST node types
+ */
+export type ASTNode = | DocumentNode
+  | TextNode
+  | ExpressionNode
+  | DirectiveNode
+  | ComponentNode
+  | ElementNode
+  | AttributeNode
+  | CommentNode
+  | ScriptNode
+  | StyleNode
+/**
+ * Token types for lexer (reserved for future tokenizer implementation)
+ */
+declare type _TokenType = | 'TEXT'
+  | 'EXPRESSION_ESCAPED'
+  | 'EXPRESSION_UNESCAPED'
+  | 'DIRECTIVE_START'
+  | 'DIRECTIVE_END'
+  | 'COMMENT_HTML'
+  | 'COMMENT_STX'
+  | 'TAG_OPEN'
+  | 'TAG_CLOSE'
+  | 'TAG_SELF_CLOSE'
+  | 'EOF'
+/**
+ * Simple template parser
+ */
+export declare class TemplateParser {
+  private source: string;
+  private pos: number;
+  private line: number;
+  private column: number;
+  private filePath?: string;
+  parse(template: string, filePath?: string): DocumentNode;
+  private parseChildren(stopAt?: RegExp): ASTNode[];
+  private parseNext(): ASTNode | null;
+  private parseText(): TextNode | null;
+  private parseExpression(escaped: boolean): ExpressionNode;
+  private parseDirective(): DirectiveNode;
+  private parseParenthesized(): string;
+  private parseStxComment(): CommentNode;
+  private parseHtmlComment(): CommentNode;
+  private parseTag(): ElementNode | ComponentNode;
+  private parseAttributes(): AttributeNode[];
+  private parseAttribute(): AttributeNode | null;
+  private parseScript(): ScriptNode;
+  private parseStyle(): StyleNode;
+  private advance(count?: number): void;
+  private skipWhitespace(): void;
+  private getPosition(): Position;
+}