@hyperfixi/vite-plugin 2.0.0

package/dist/index.d.cts

@@ -0,0 +1,404 @@
+import { Plugin } from 'vite';
+import { ASTNode } from '@hyperfixi/core/parser/hybrid/ast-types';
+
+/**
+ * Vite Plugin Types
+ *
+ * Type definitions for the HyperFixi Vite plugin.
+ */
+/**
+ * Options for the HyperFixi Vite plugin
+ */
+interface HyperfixiPluginOptions {
+    /**
+     * Bundle generation mode:
+     * - 'interpret': Generate minimal bundle with parser (default, ~8KB gzip)
+     * - 'compile': Pre-compile hyperscript to JS at build time (~500 bytes gzip)
+     *
+     * Compile mode limitations:
+     * - No dynamic hyperscript (runtime execute() won't work)
+     * - No block commands (if, for, repeat, while, fetch)
+     * - HTML must be transformed to use data-h attributes
+     *
+     * Use compile mode when:
+     * - Bundle size is critical (<1KB target)
+     * - All hyperscript is static (no dynamic generation)
+     * - Only simple commands are used (toggle, add, remove, set, etc.)
+     */
+    mode?: 'interpret' | 'compile';
+    /**
+     * File patterns to scan for hyperscript usage.
+     * Defaults to common web file extensions.
+     */
+    include?: RegExp | string[];
+    /**
+     * File patterns to exclude from scanning.
+     * Defaults to node_modules.
+     */
+    exclude?: RegExp | string[];
+    /**
+     * Extra commands to always include in the bundle.
+     * Use this for dynamically generated hyperscript that can't be detected.
+     */
+    extraCommands?: string[];
+    /**
+     * Extra blocks to always include in the bundle.
+     */
+    extraBlocks?: string[];
+    /**
+     * Always include positional expressions (first, last, next, closest, parent).
+     * Set to true if your dynamic code uses these.
+     */
+    positional?: boolean;
+    /**
+     * Enable HTMX integration (auto-process after htmx:afterSettle).
+     */
+    htmx?: boolean;
+    /**
+     * Development mode fallback strategy.
+     * - 'hybrid-complete': Use pre-built hybrid-complete bundle for faster dev (default)
+     * - 'full': Use full bundle for complete compatibility
+     * - 'auto': Generate minimal bundle even in dev
+     */
+    devFallback?: 'hybrid-complete' | 'full' | 'auto';
+    /**
+     * Global variable name for the hyperfixi API.
+     * Defaults to 'hyperfixi'.
+     */
+    globalName?: string;
+    /**
+     * Bundle name for generated code comments.
+     * Defaults to 'ViteAutoGenerated'.
+     */
+    bundleName?: string;
+    /**
+     * Enable verbose logging during development.
+     */
+    debug?: boolean;
+    /**
+     * Enable semantic parsing for multilingual support.
+     * - false: No semantic parsing (default, current behavior)
+     * - true: Auto-detect languages from templates
+     * - 'en': English semantic only (synonyms, flexible syntax)
+     * - 'auto': Same as true
+     */
+    semantic?: boolean | 'en' | 'auto';
+    /**
+     * Explicit language list (overrides auto-detection).
+     * Use ISO 639-1 codes: 'en', 'es', 'ja', 'ko', 'zh', 'ar', etc.
+     */
+    languages?: string[];
+    /**
+     * Regional bundle shorthand (alternative to explicit languages).
+     * - 'western': en, es, pt, fr, de, it
+     * - 'east-asian': ja, zh, ko
+     * - 'slavic': pl, ru, uk
+     * - 'south-asian': hi, bn
+     * - 'priority': 13 most common languages
+     * - 'all': All 21 supported languages
+     */
+    region?: 'western' | 'east-asian' | 'slavic' | 'south-asian' | 'priority' | 'all';
+    /**
+     * Enable grammar transformation for native word order.
+     * When true, semantic is automatically enabled.
+     * Adds support for SOV (Japanese, Korean) and VSO (Arabic) word orders.
+     */
+    grammar?: boolean;
+    /**
+     * Always include these languages in addition to detected ones.
+     * Useful for dynamic content not detectable at build time.
+     */
+    extraLanguages?: string[];
+    /**
+     * Custom language keyword definitions.
+     * Use this to add new languages or extend/override existing keyword detection.
+     *
+     * @example
+     * ```typescript
+     * hyperfixi({
+     *   customKeywords: {
+     *     // Add a new language
+     *     'my-lang': {
+     *       keywords: new Set(['mytoggle', 'myadd', 'myremove']),
+     *       isNonLatin: false,
+     *     },
+     *     // Extend an existing language with additional keywords
+     *     'es': {
+     *       keywords: new Set(['conmutar', 'intercambiar']),  // Additional Spanish keywords
+     *       extend: true,  // Merge with existing keywords
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    customKeywords?: Record<string, CustomLanguageKeywords>;
+}
+/**
+ * Custom language keyword configuration.
+ */
+interface CustomLanguageKeywords {
+    /**
+     * Set of keywords for this language.
+     */
+    keywords: Set<string>;
+    /**
+     * Whether this language uses non-Latin script.
+     * Non-Latin scripts use simple substring matching (no word boundaries).
+     * Latin scripts use word boundary matching to avoid false positives.
+     */
+    isNonLatin?: boolean;
+    /**
+     * If true, merge these keywords with existing ones for this language.
+     * If false (default), replace existing keywords entirely.
+     */
+    extend?: boolean;
+}
+/**
+ * HTMX/Fixi attribute usage information
+ */
+interface HtmxUsage {
+    /** Whether any htmx attributes were found */
+    hasHtmxAttributes: boolean;
+    /** Whether any fixi-specific attributes were found (fx-action, etc.) */
+    hasFixiAttributes: boolean;
+    /** HTTP methods used (GET, POST, PUT, PATCH, DELETE) */
+    httpMethods: Set<string>;
+    /** Swap strategies used (innerHTML, morph, delete, beforeend, etc.) */
+    swapStrategies: Set<string>;
+    /** hx-on:* handler values (raw hyperscript) */
+    onHandlers: string[];
+    /** Trigger modifiers detected (debounce, throttle, once) */
+    triggerModifiers: Set<string>;
+    /** URL management strategies (push-url, replace-url) */
+    urlManagement: Set<string>;
+    /** Whether hx-confirm is used */
+    usesConfirm: boolean;
+}
+/**
+ * Usage information detected from a single file
+ */
+interface FileUsage {
+    /** Commands used in this file */
+    commands: Set<string>;
+    /** Block types used (if, repeat, for, while, fetch) */
+    blocks: Set<string>;
+    /** Whether positional expressions are used */
+    positional: boolean;
+    /** Non-English languages detected in hyperscript (ISO 639-1 codes) */
+    detectedLanguages: Set<string>;
+    /** HTMX/Fixi attribute usage (if detected) */
+    htmx?: HtmxUsage;
+}
+/**
+ * Aggregated usage information across all files
+ */
+interface AggregatedUsage {
+    /** All commands detected across all files */
+    commands: Set<string>;
+    /** All blocks detected across all files */
+    blocks: Set<string>;
+    /** Whether any file uses positional expressions */
+    positional: boolean;
+    /** All non-English languages detected across all files */
+    detectedLanguages: Set<string>;
+    /** Aggregated HTMX/Fixi usage across all files */
+    htmx: HtmxUsage;
+    /** Map of file paths to their usage */
+    fileUsage: Map<string, FileUsage>;
+}
+
+/**
+ * Compiler
+ *
+ * Compiles hyperscript AST to JavaScript at build time.
+ * Eliminates the need for runtime parsing.
+ *
+ * Multilingual support:
+ * - For English: Uses HybridParser directly
+ * - For other languages: Uses semantic parser to translate → AST → JavaScript
+ * - Semantic parsing happens at BUILD time (zero runtime overhead)
+ */
+
+/**
+ * Semantic analyzer interface for multilingual support.
+ * This matches the interface from @lokascript/semantic.
+ */
+interface SemanticAnalysisResult {
+    confidence: number;
+    node?: unknown;
+    errors?: string[];
+}
+interface SemanticAnalyzer {
+    analyze(input: string, language: string): SemanticAnalysisResult;
+    supportsLanguage(language: string): boolean;
+}
+type BuildASTFn = (node: unknown) => {
+    ast: ASTNode;
+    warnings: string[];
+};
+/**
+ * Configure the semantic parser for multilingual compilation.
+ * Call this with the semantic analyzer from @lokascript/semantic.
+ *
+ * @example
+ * ```typescript
+ * import { createSemanticAnalyzer, buildAST } from '@lokascript/semantic';
+ * import { setSemanticParser } from '@hyperfixi/vite-plugin';
+ *
+ * setSemanticParser(createSemanticAnalyzer(), buildAST);
+ * ```
+ */
+declare function setSemanticParser(analyzer: SemanticAnalyzer, buildAST: BuildASTFn): void;
+/**
+ * Clear the semantic parser (for testing).
+ */
+declare function clearSemanticParser(): void;
+/**
+ * Check if semantic parser is available.
+ */
+declare function hasSemanticParser(): boolean;
+interface CompiledHandler {
+    /** Unique handler ID (h0, h1, etc.) */
+    id: string;
+    /** Event name (click, input, etc.) */
+    event: string;
+    /** Event modifiers */
+    modifiers: {
+        prevent?: boolean;
+        stop?: boolean;
+        once?: boolean;
+        debounce?: number;
+        throttle?: number;
+    };
+    /** Compiled JavaScript code */
+    code: string;
+    /** Whether handler needs the mini-evaluator for dynamic expressions */
+    needsEvaluator: boolean;
+    /** Original hyperscript for debugging */
+    original: string;
+}
+/**
+ * Compile options for multilingual support.
+ */
+interface CompileOptions {
+    /** Language code (ISO 639-1). Defaults to 'en'. */
+    language?: string;
+    /** Enable debug logging. */
+    debug?: boolean;
+}
+
+/**
+ * Language Keywords for Detection
+ *
+ * Maps of keywords for each of the 21 supported languages.
+ * Used by the scanner to detect which languages are used in hyperscript templates.
+ *
+ * Note: These are a representative subset of keywords - enough to reliably
+ * detect language usage without including every possible keyword variant.
+ */
+
+/**
+ * All supported language codes.
+ */
+declare const SUPPORTED_LANGUAGES: readonly ["en", "es", "pt", "fr", "de", "it", "vi", "pl", "ru", "uk", "ja", "zh", "ko", "ar", "hi", "bn", "th", "tr", "id", "sw", "qu", "tl"];
+type SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];
+/**
+ * Regional bundle mappings.
+ */
+declare const REGIONS: {
+    western: SupportedLanguage[];
+    'east-asian': SupportedLanguage[];
+    slavic: SupportedLanguage[];
+    'south-asian': SupportedLanguage[];
+    priority: SupportedLanguage[];
+    all: SupportedLanguage[];
+};
+/**
+ * Detect all languages used in a hyperscript string.
+ * Returns a Set of language codes found.
+ *
+ * Note: English is never detected (it's the default).
+ * Only non-English languages are detected.
+ */
+declare function detectLanguages(script: string): Set<SupportedLanguage>;
+/**
+ * Register custom keywords for a language.
+ * Call this before scanning to add or extend language detection.
+ *
+ * @param code - Language code (e.g., 'es', 'my-lang')
+ * @param config - Keyword configuration
+ */
+declare function registerCustomKeywords(code: string, config: CustomLanguageKeywords): void;
+/**
+ * Get keywords for a language, including custom registrations.
+ */
+declare function getKeywordsForLanguage(code: string): Set<string> | undefined;
+/**
+ * Check if a language uses non-Latin script.
+ */
+declare function isNonLatinLanguage(code: string): boolean;
+/**
+ * Get all registered language codes (built-in + custom).
+ */
+declare function getAllLanguageCodes(): string[];
+/**
+ * Clear all custom keyword registrations.
+ */
+declare function clearCustomKeywords(): void;
+/**
+ * Get the optimal regional bundle for a set of detected languages.
+ * Returns the smallest bundle that covers all detected languages.
+ */
+declare function getOptimalRegion(languages: Set<SupportedLanguage>): 'western' | 'east-asian' | 'slavic' | 'south-asian' | 'priority' | 'all' | null;
+
+/**
+ * @hyperfixi/vite-plugin
+ *
+ * Zero-config Vite plugin that automatically generates minimal HyperFixi bundles
+ * based on detected hyperscript usage in your source files.
+ *
+ * @example
+ * ```javascript
+ * // vite.config.js
+ * import { hyperfixi } from '@hyperfixi/vite-plugin';
+ *
+ * export default {
+ *   plugins: [hyperfixi()]
+ * };
+ * ```
+ *
+ * The plugin automatically:
+ * - Scans HTML, Vue, Svelte, JSX/TSX files for `_="..."` attributes
+ * - Detects which commands, blocks, and expressions are used
+ * - Generates a minimal bundle with only needed features
+ * - Re-generates on file changes (HMR)
+ *
+ * @example
+ * ```javascript
+ * // With options
+ * hyperfixi({
+ *   extraCommands: ['fetch', 'put'],  // Always include these commands
+ *   htmx: true,                       // Enable htmx integration
+ *   debug: true,                      // Enable verbose logging
+ * })
+ * ```
+ *
+ * @example
+ * ```javascript
+ * // Compile mode for smallest bundles (~500 bytes)
+ * hyperfixi({
+ *   mode: 'compile',  // Pre-compile hyperscript to JS
+ *   debug: true,
+ * })
+ * ```
+ */
+
+/**
+ * Create the HyperFixi Vite plugin
+ *
+ * @param options Plugin options
+ * @returns Vite plugin
+ */
+declare function hyperfixi(options?: HyperfixiPluginOptions): Plugin;
+
+export { type AggregatedUsage, type CompileOptions, type CompiledHandler, type CustomLanguageKeywords, type FileUsage, type HyperfixiPluginOptions, REGIONS, SUPPORTED_LANGUAGES, type SupportedLanguage, clearCustomKeywords, clearSemanticParser, hyperfixi as default, detectLanguages, getAllLanguageCodes, getKeywordsForLanguage, getOptimalRegion, hasSemanticParser, hyperfixi, isNonLatinLanguage, registerCustomKeywords, setSemanticParser };