sibujs 1.0.0-beta.1

package/dist/build.d.ts

@@ -0,0 +1,630 @@
+/**
+ * Official Vite plugin for SibuJS.
+ * Provides optimized builds, automatic component detection, and development enhancements.
+ */
+interface SibuVitePluginOptions {
+    /** Enable HMR support for SibuJS components */
+    hmr?: boolean;
+    /** Enable automatic pure annotations for tree-shaking */
+    pureAnnotations?: boolean;
+    /** Component file patterns to watch */
+    include?: string[];
+    /** File patterns to exclude */
+    exclude?: string[];
+    /** Enable dev mode features (devtools, debug logging) */
+    devMode?: boolean;
+    /** Enable static template optimization (default: true in production) */
+    staticOptimize?: boolean;
+    /** Compile html`` tagged templates to direct function calls (default: true in production) */
+    compileTemplates?: boolean;
+}
+/**
+ * Vite plugin configuration for SibuJS projects.
+ * Returns a Vite-compatible plugin object.
+ *
+ * Note: This is a configuration helper. For full Vite plugin functionality,
+ * users should install @sibu/vite-plugin (when available).
+ */
+declare function sibuVitePlugin(options?: SibuVitePluginOptions): {
+    name: string;
+    enforce?: "pre" | "post";
+    config?: () => Record<string, unknown>;
+    transform?: (code: string, id: string) => {
+        code: string;
+        map?: unknown;
+    } | null;
+    handleHotUpdate?: (ctx: {
+        file: string;
+        modules: unknown[];
+    }) => void;
+};
+/**
+ * Generate an optimized Vite configuration for SibuJS projects.
+ */
+declare function createViteConfig(options?: {
+    /** Entry point */
+    entry?: string;
+    /** Output directory */
+    outDir?: string;
+    /** Enable SSR mode */
+    ssr?: boolean;
+    /** Additional Vite config overrides */
+    overrides?: Record<string, unknown>;
+}): Record<string, unknown>;
+
+/**
+ * Webpack plugin configuration for SibuJS projects.
+ * Provides build optimization, pure annotations, and development enhancements.
+ */
+interface SibuWebpackPluginOptions {
+    /** Enable automatic pure annotations for tree-shaking */
+    pureAnnotations?: boolean;
+    /** Enable dev mode features (devtools, debug logging) */
+    devMode?: boolean;
+}
+/**
+ * Webpack plugin configuration helper for SibuJS.
+ * Returns webpack-compatible plugin and loader configurations.
+ *
+ * Usage:
+ * ```js
+ * const { sibuWebpackPlugin } = require('sibu/src/build/webpack');
+ * module.exports = {
+ *   plugins: [sibuWebpackPlugin()],
+ * };
+ * ```
+ */
+/** Minimal webpack compiler interface for plugin compatibility. */
+interface WebpackCompiler {
+    hooks?: Record<string, {
+        tap: (name: string, callback: (...args: unknown[]) => void) => void;
+    } | undefined>;
+    options: {
+        module?: {
+            rules?: unknown[];
+        };
+        resolve?: {
+            mainFields?: string[];
+        };
+        plugins?: unknown[];
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+declare function sibuWebpackPlugin(options?: SibuWebpackPluginOptions): {
+    /** Plugin name */
+    name: string;
+    /** Apply function for webpack plugin API */
+    apply: (compiler: WebpackCompiler) => void;
+};
+/**
+ * Create a standalone webpack loader function for pure annotation injection.
+ * Can be used directly in webpack module rules.
+ */
+declare function createPureAnnotationsLoader(): (source: string) => string;
+/**
+ * Generate Webpack configuration for SibuJS projects.
+ *
+ * Usage:
+ * ```js
+ * const { createWebpackConfig } = require('sibu/src/build/webpack');
+ * module.exports = createWebpackConfig({
+ *   entry: './src/index.ts',
+ *   mode: 'production',
+ * });
+ * ```
+ */
+declare function createWebpackConfig(options?: {
+    /** Entry point file */
+    entry?: string;
+    /** Output directory path */
+    outputPath?: string;
+    /** Build mode */
+    mode?: "development" | "production";
+}): Record<string, unknown>;
+
+/**
+ * CDN distribution utilities for SibuJS.
+ * Supports UMD builds for script tag usage and CDN delivery.
+ */
+/**
+ * Register SibuJS on the global window object for CDN/script tag usage.
+ * Makes all exports available as window.Sibu.
+ *
+ * Usage (in a script tag):
+ * ```html
+ * <script src="https://unpkg.com/sibu@latest/dist/cdn.global.js"></script>
+ * <script>
+ *   const { div, span, mount, signal } = window.Sibu;
+ *   // Use SibuJS without a bundler
+ * </script>
+ * ```
+ */
+declare function registerGlobal(): void;
+/**
+ * Generate a UMD (Universal Module Definition) wrapper for a SibuJS module.
+ * The wrapper supports AMD (RequireJS), CommonJS (Node.js), and browser globals.
+ *
+ * @param name - The global variable name for browser usage
+ * @param factory - Factory function that returns the module's exports
+ * @returns The UMD wrapper code as a string
+ */
+declare function umdWrapper(name: string, factory: () => unknown): string;
+/**
+ * CDN URL helpers for common CDN providers.
+ * Generates URLs for including SibuJS from popular CDN services.
+ */
+declare const cdnUrls: {
+    /**
+     * Generate an unpkg CDN URL.
+     * @param version - Package version (defaults to 'latest')
+     */
+    unpkg: (version?: string) => string;
+    /**
+     * Generate a jsDelivr CDN URL.
+     * @param version - Package version (defaults to 'latest')
+     */
+    jsdelivr: (version?: string) => string;
+    /**
+     * Generate a Skypack CDN URL (ESM-native).
+     * @param version - Package version (defaults to 'latest')
+     */
+    skypack: (version?: string) => string;
+    /**
+     * Generate a complete HTML script tag for including SibuJS from a CDN.
+     *
+     * @param provider - CDN provider to use (defaults to 'jsdelivr')
+     * @param version - Package version (defaults to 'latest')
+     * @returns An HTML script tag string
+     *
+     * @example
+     * ```ts
+     * cdnUrls.scriptTag('jsdelivr', '1.0.0')
+     * // => '<script src="https://cdn.jsdelivr.net/npm/sibu@1.0.0/dist/cdn.global.js"></script>'
+     * ```
+     */
+    scriptTag: (provider?: "unpkg" | "jsdelivr" | "skypack", version?: string) => string;
+};
+/**
+ * Generate an import map for SibuJS modules.
+ * Useful for browser-native ES modules without a bundler.
+ *
+ * Import maps allow browsers to resolve bare module specifiers like
+ * `import { div } from 'sibu'` without a build step.
+ *
+ * @param baseUrl - Base URL for module resolution (defaults to jsDelivr)
+ * @returns An import map object with serialization helpers
+ *
+ * @example
+ * ```ts
+ * const map = generateImportMap();
+ * document.head.innerHTML += map.toScriptTag();
+ *
+ * // Now you can use bare specifiers in module scripts:
+ * // <script type="module">
+ * //   import { div, mount } from 'sibu';
+ * // </script>
+ * ```
+ */
+declare function generateImportMap(baseUrl?: string): {
+    imports: Record<string, string>;
+    toJSON: () => string;
+    toScriptTag: () => string;
+};
+
+/**
+ * TypeScript declaration map utilities for SibuJS.
+ * Provides tsconfig helpers and declaration generation support
+ * for improved IDE experience and type-safe development.
+ */
+/**
+ * Generate a recommended tsconfig.json for SibuJS projects.
+ *
+ * @param options - Customization options for the generated configuration
+ * @returns A complete tsconfig.json object
+ *
+ * @example
+ * ```ts
+ * import { generateTsConfig } from 'sibu/src/build/declarations';
+ * import { writeFileSync } from 'fs';
+ *
+ * const config = generateTsConfig({ outDir: './dist' });
+ * writeFileSync('tsconfig.json', JSON.stringify(config, null, 2));
+ * ```
+ */
+declare function generateTsConfig(options?: {
+    /** TypeScript compilation target (default: 'ES2020') */
+    target?: string;
+    /** Output directory for compiled files */
+    outDir?: string;
+    /** Enable declaration map generation (default: true) */
+    declarationMap?: boolean;
+    /** Additional path aliases */
+    paths?: Record<string, string[]>;
+}): Record<string, unknown>;
+/**
+ * Validate that a project's TypeScript configuration is compatible with SibuJS.
+ *
+ * Checks for required settings, warns about suboptimal configurations,
+ * and suggests improvements for the best development experience.
+ *
+ * @param config - The tsconfig.json object to validate (the full config, including compilerOptions)
+ * @returns Validation result with warnings and suggestions
+ *
+ * @example
+ * ```ts
+ * import { validateTsConfig } from 'sibu/src/build/declarations';
+ * import { readFileSync } from 'fs';
+ *
+ * const tsconfig = JSON.parse(readFileSync('tsconfig.json', 'utf-8'));
+ * const result = validateTsConfig(tsconfig);
+ *
+ * if (!result.valid) {
+ *   console.error('TypeScript configuration issues:', result.warnings);
+ * }
+ * result.suggestions.forEach(s => console.log('Suggestion:', s));
+ * ```
+ */
+declare function validateTsConfig(config: Record<string, unknown>): {
+    valid: boolean;
+    warnings: string[];
+    suggestions: string[];
+};
+
+/**
+ * Bundle size analysis utilities for SibuJS.
+ * Provides tools to analyze, estimate, and report on bundle sizes
+ * for SibuJS projects.
+ */
+/**
+ * Known approximate sizes (in bytes, minified + gzipped) for SibuJS modules.
+ * These estimates are based on the typical compiled output of each module
+ * and are useful for pre-build size budgeting.
+ */
+declare const moduleSizes: Record<string, number>;
+/**
+ * Analyze module sizes and dependencies.
+ *
+ * Takes a record of module names to their source code and computes
+ * size statistics for each module and the total bundle.
+ *
+ * @param modules - A map of module names to their source code strings
+ * @returns Analysis results with sizes, sorted rankings, and a report generator
+ *
+ * @example
+ * ```ts
+ * import { analyzeBundle } from 'sibu/src/build/analyzer';
+ *
+ * const result = analyzeBundle({
+ *   'app.ts': appSourceCode,
+ *   'components/Header.ts': headerSourceCode,
+ *   'components/Footer.ts': footerSourceCode,
+ * });
+ *
+ * console.log(result.report());
+ * // Total: 12.5 KB
+ * // app.ts: 8.2 KB (65.6%)
+ * // components/Header.ts: 2.8 KB (22.4%)
+ * // components/Footer.ts: 1.5 KB (12.0%)
+ * ```
+ */
+declare function analyzeBundle(modules: Record<string, string>): {
+    /** Total bundle size in bytes */
+    totalSize: number;
+    /** Size per module in bytes */
+    moduleSizes: Record<string, number>;
+    /** Modules sorted by size (largest first) */
+    sorted: Array<{
+        name: string;
+        size: number;
+        percentage: number;
+    }>;
+    /** Format as human-readable report */
+    report: () => string;
+};
+/**
+ * Estimate the impact of importing specific SibuJS modules.
+ * Based on known approximate sizes of each module (minified + gzipped).
+ *
+ * This is useful for understanding the cost of specific imports
+ * before building, enabling informed decisions about which features to use.
+ *
+ * @param imports - Array of module paths to estimate (e.g., ['core/signal', 'core/html'])
+ * @returns Estimated size information with breakdown
+ *
+ * @example
+ * ```ts
+ * import { estimateImportSize } from 'sibu/src/build/analyzer';
+ *
+ * // Estimate cost of a minimal SibuJS app
+ * const estimate = estimateImportSize([
+ *   'core/html',
+ *   'core/mount',
+ *   'core/signal',
+ *   'core/effect',
+ *   'reactivity/track',
+ *   'reactivity/batch',
+ * ]);
+ *
+ * console.log(estimate.formatted);
+ * // Estimated bundle size: 3.17 KB (minified + gzipped)
+ * //   core/html: 1.76 KB
+ * //   core/effect: 0.34 KB
+ * //   ...
+ * ```
+ */
+declare function estimateImportSize(imports: string[]): {
+    /** Total estimated size in bytes */
+    estimated: number;
+    /** Size breakdown per module */
+    breakdown: Record<string, number>;
+    /** Human-readable formatted output */
+    formatted: string;
+};
+
+/**
+ * ESLint plugin configuration for SibuJS best practices.
+ * Provides rule definitions that can be used with an ESLint plugin.
+ */
+interface LintViolation {
+    rule: string;
+    message: string;
+    severity: "error" | "warning";
+    line?: number;
+    column?: number;
+}
+/**
+ * Static analysis rules for SibuJS code.
+ * These check source code strings for common mistakes and anti-patterns.
+ */
+declare const lintRules: {
+    /** Detect signal inside loops or conditionals */
+    "no-signals-in-conditionals": {
+        name: "no-signals-in-conditionals";
+        description: string;
+        check(source: string): LintViolation[];
+    };
+    /** Detect missing cleanup in effect */
+    "effect-cleanup": {
+        name: "effect-cleanup";
+        description: string;
+        check(source: string): LintViolation[];
+    };
+    /** Detect direct DOM mutation outside of reactive context */
+    "no-direct-dom-mutation": {
+        name: "no-direct-dom-mutation";
+        description: string;
+        check(source: string): LintViolation[];
+    };
+    /** Detect missing key prop in each() calls */
+    "each-requires-key": {
+        name: "each-requires-key";
+        description: string;
+        check(source: string): LintViolation[];
+    };
+    /** Detect unused reactive state */
+    "no-unused-state": {
+        name: "no-unused-state";
+        description: string;
+        check(source: string): LintViolation[];
+    };
+};
+/**
+ * Run all lint rules on source code.
+ */
+declare function lintSource(source: string, rules?: string[]): LintViolation[];
+/**
+ * Generate ESLint plugin configuration.
+ * Returns a config object that can be used in .eslintrc.
+ */
+declare function generateEslintConfig(options?: {
+    severity?: "error" | "warning";
+}): Record<string, unknown>;
+
+/**
+ * IDE extension support for SibuJS.
+ * Provides metadata and utilities for VS Code and other IDE integrations.
+ */
+/**
+ * Component metadata for IDE IntelliSense.
+ */
+interface ComponentMeta {
+    name: string;
+    description: string;
+    props: Array<{
+        name: string;
+        type: string;
+        required: boolean;
+        default?: string;
+        description: string;
+    }>;
+    events?: Array<{
+        name: string;
+        description: string;
+    }>;
+}
+/**
+ * SibuJS component registry for IDE auto-completion.
+ * Returns metadata about all built-in SibuJS exports.
+ */
+declare function getComponentMetadata(): ComponentMeta[];
+/**
+ * Generate VS Code snippets for SibuJS.
+ */
+declare function generateVSCodeSnippets(): Record<string, {
+    prefix: string;
+    body: string[];
+    description: string;
+}>;
+/**
+ * Generate a language configuration for SibuJS files.
+ * Provides bracket matching, comment toggling, and auto-close pairs.
+ */
+declare function generateLanguageConfig(): {
+    comments: {
+        lineComment: string;
+        blockComment: [string, string];
+    };
+    brackets: [string, string][];
+    autoClosingPairs: Array<{
+        open: string;
+        close: string;
+    }>;
+};
+/**
+ * Generate type stubs for common SibuJS patterns.
+ * Useful for IDE auto-import suggestions.
+ */
+declare function generateTypeStubs(): Record<string, string>;
+
+/**
+ * Static analysis utilities for SibuJS build-time optimizations.
+ * Detects tagFactory calls that can be converted to template cloning.
+ */
+interface StaticAnalysisResult {
+    /** Whether any static patterns were found */
+    hasStaticPatterns: boolean;
+    /** Detected static patterns with replacement info */
+    patterns: Array<{
+        /** Original source code of the call */
+        original: string;
+        /** The tag name (e.g., "div", "span") */
+        tag: string;
+        /** Static HTML that can be used as a template */
+        templateHtml: string;
+        /** Start index in original source */
+        start: number;
+        /** End index in original source */
+        end: number;
+    }>;
+}
+/**
+ * Analyze source code for static tagFactory patterns that can be
+ * converted to template cloning at build time.
+ *
+ * Detects patterns like:
+ *   div({ class: "card", id: "main", nodes: "Hello" })
+ *
+ * And identifies them as candidates for:
+ *   staticTemplate('<div class="card" id="main">Hello</div>')
+ */
+declare function analyzeStaticTemplates(code: string): StaticAnalysisResult;
+
+/**
+ * Build-time compiler for SibuJS html tagged templates.
+ *
+ * Transforms:
+ *   html`<div class=${cls}><span>${() => count()}</span></div>`
+ *
+ * Into direct tagFactory calls:
+ *   div({ class: __v[0], nodes: [span({ nodes: __v[1] })] })
+ *
+ * This eliminates the runtime template parser entirely, removing the ~1.5x
+ * overhead of the html`` authoring style vs direct function calls.
+ *
+ * The runtime parser remains available as a fallback for users who don't
+ * use a build step.
+ */
+interface CompileResult {
+    /** The transformed source code, or null if no templates found */
+    code: string | null;
+    /** Set of HTML tag names used (need to be imported from sibu) */
+    usedTags: Set<string>;
+    /** Whether any SVG tags were used (needs tagFactory + SVG_NS import) */
+    usesSvg: boolean;
+    /** Number of templates compiled */
+    compiledCount: number;
+}
+/**
+ * Compile all html`` tagged templates in source code to direct tagFactory calls.
+ *
+ * Transforms:
+ *   html`<div class=${cls}><span>${text}</span></div>`
+ *
+ * Into:
+ *   ((v) => div({ class: v[0], nodes: [span({ nodes: v[1] })] }))([cls, text])
+ *
+ * This eliminates the runtime template parser entirely.
+ */
+declare function compileHtmlTemplates(code: string): CompileResult;
+
+/**
+ * Vite plugin for automatic route-based code splitting.
+ * Scans a routes directory and generates lazy-loaded route definitions.
+ */
+interface RouteSplittingOptions {
+    /** Directory containing route files (default: "src/routes") */
+    routesDir?: string;
+    /** Glob patterns to exclude */
+    exclude?: string[];
+    /** Chunk name prefix (default: "route-") */
+    chunkPrefix?: string;
+}
+interface RouteEntry {
+    /** URL path pattern (e.g., "/users/:id") */
+    path: string;
+    /** Import path relative to project root */
+    importPath: string;
+    /** Generated chunk name */
+    chunkName: string;
+    /** Whether route has dynamic segments */
+    isDynamic: boolean;
+}
+/**
+ * Convert a file path within the routes directory to a URL pattern.
+ *
+ * Conventions:
+ * - index.ts -> /
+ * - about.ts -> /about
+ * - users/[id].ts -> /users/:id
+ * - blog/[...slug].ts -> /blog/*
+ * - _layout.ts -> skipped (layout file)
+ * - _middleware.ts -> skipped
+ */
+declare function fileToRoute(relativePath: string): string | null;
+/**
+ * Generate route entries from scanned files.
+ */
+declare function buildRouteEntries(files: string[], chunkPrefix: string): RouteEntry[];
+/**
+ * Vite plugin for automatic route-based code splitting.
+ *
+ * Scans the routes directory and generates a virtual module `virtual:sibu-routes`
+ * that exports lazy-loaded route definitions compatible with Sibu's router.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { sibuVitePlugin } from "sibu/build";
+ * import { sibuRouteSplitting } from "sibu/build";
+ *
+ * export default {
+ *   plugins: [sibuVitePlugin(), sibuRouteSplitting()],
+ * };
+ *
+ * // In your app:
+ * import { routes } from "virtual:sibu-routes";
+ * import { setRoutes } from "sibu/plugins";
+ * setRoutes(routes);
+ * ```
+ */
+declare function sibuRouteSplitting(options?: RouteSplittingOptions): {
+    name: string;
+    enforce: "pre";
+    resolveId: (id: string) => string | undefined;
+    load: (id: string) => Promise<string | undefined>;
+    handleHotUpdate?: (ctx: {
+        file: string;
+        server: {
+            moduleGraph: {
+                invalidateModule: (mod: unknown) => void;
+                getModuleById: (id: string) => unknown;
+            };
+            ws: {
+                send: (msg: unknown) => void;
+            };
+        };
+    }) => void;
+};
+
+export { type CompileResult, type ComponentMeta, type LintViolation, type RouteSplittingOptions, type SibuVitePluginOptions, type SibuWebpackPluginOptions, type StaticAnalysisResult, analyzeBundle, analyzeStaticTemplates, buildRouteEntries, cdnUrls, compileHtmlTemplates, createPureAnnotationsLoader, createViteConfig, createWebpackConfig, estimateImportSize, fileToRoute, generateEslintConfig, generateImportMap, generateLanguageConfig, generateTsConfig, generateTypeStubs, generateVSCodeSnippets, getComponentMetadata, lintRules, lintSource, moduleSizes, registerGlobal, sibuRouteSplitting, sibuVitePlugin, sibuWebpackPlugin, umdWrapper, validateTsConfig };