@jasonshimmy/custom-elements-runtime 3.4.0 → 3.5.0

package/dist/vite-plugin.d.ts

@@ -1,7 +1,8 @@
 /**
- * Vite plugins for build-time JIT CSS generation and SSR configuration.
+ * Vite plugins for build-time JIT CSS generation, SSR configuration, and
+ * per-page component code splitting.
  *
- * Two plugins are exported:
+ * Three plugins are exported:
  *
  * - **`cerJITCSS`** — Scans source files for utility class names and emits
  *   pre-generated CSS, eliminating all runtime parsing cost for projects with
@@ -12,6 +13,18 @@
  *   resolved SSR render options so server entry files can import and use them
  *   without duplication.
  *
+ * - **`cerComponentImports`** — Transform plugin that scans each app file for
+ *   custom element tags used in `html\`` template literals and injects static
+ *   `import` statements pointing to the corresponding component source files.
+ *   This gives Rollup the module graph edges it needs to automatically
+ *   code-split components per page chunk.
+ *
+ * Three build-time utilities are also exported:
+ *
+ * - **`resolveTagName`** — Normalize a component name to its registered tag name.
+ * - **`extractTemplateTagNames`** — Extract hyphenated tag names from `html\`` sources.
+ * - **`extractComponentRegistrations`** — Extract registered tag names from `component()` calls.
+ *
  * @example cerJITCSS only
  * ```ts
  * // vite.config.ts
@@ -55,9 +68,26 @@
  *
  * const { htmlWithStyles } = renderToStringWithJITCSS(appVNode, ssrConfig);
  * ```
+ *
+ * @example cerComponentImports for per-page code splitting
+ * ```ts
+ * // vite.config.ts
+ * import { defineConfig } from 'vite';
+ * import { cerComponentImports } from '@jasonshimmy/custom-elements-runtime/vite-plugin';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     cerComponentImports({
+ *       componentsDir: '/absolute/path/to/app/components',
+ *       appRoot: '/absolute/path/to/app',
+ *     }),
+ *   ],
+ * });
+ * ```
  */
 import type { Plugin } from 'vite';
 import { type JITCSSOptions } from './runtime/style';
+import { resolveTagName as _resolveTagName } from './runtime/tag-utils';
 /**
  * Options for the `cerJITCSS` Vite plugin.
  */
@@ -140,3 +170,67 @@ export declare function cerPlugin(options: CerPluginOptions): Plugin[];
  * pre-generated JIT CSS as a file and/or `virtual:cer-jit-css` module.
  */
 export declare function cerJITCSS(options: CerJITCSSPluginOptions): Plugin;
+/**
+ * Resolves a component() tag argument to the actual registered tag name.
+ * Re-exported from runtime/tag-utils so consumers have a single import surface.
+ *
+ * Rules:
+ *   camelCase → kebab-case   (myButton  → my-button)
+ *   no hyphen  → cer- prefix (app       → cer-app)
+ *   has hyphen → unchanged   (ks-badge  → ks-badge)
+ */
+export declare const resolveTagName: typeof _resolveTagName;
+/**
+ * Scan TypeScript source text for all custom element tag names referenced
+ * in html`` template literals.
+ *
+ * Strips line (//) and block (/* *\/) comments first to avoid false
+ * positives from commented-out code.
+ *
+ * Returns a Set of already-hyphenated tag names as they appear in the source
+ * (e.g. "ks-badge", "cer-app"). Single-word names that would receive a
+ * "cer-" prefix at runtime never appear as bare tags in templates — they
+ * always appear as "cer-something" — so no normalization is needed here.
+ *
+ * Closing tags (</ks-badge>) do NOT match because the regex requires the
+ * first character after < to be [a-z], not /.
+ */
+export declare function extractTemplateTagNames(source: string): Set<string>;
+/**
+ * Extract all component tag names registered in a component source file.
+ * Handles files that call component() more than once (returns all of them).
+ *
+ * Uses \bcomponent\( so it matches the standalone function name but not
+ * names like importComponent( or registerComponent(.
+ *
+ * Returns resolved (normalized) tag names, ready to match against the output
+ * of extractTemplateTagNames().
+ */
+export declare function extractComponentRegistrations(source: string): string[];
+/**
+ * Options for the {@link cerComponentImports} Vite plugin.
+ */
+export interface CerComponentImportsOptions {
+    /**
+     * Absolute path to the directory containing component files.
+     * Every .ts file found here is scanned for component() registrations.
+     */
+    componentsDir: string;
+    /**
+     * Absolute path to the app source root. The transform is restricted to
+     * files under this directory so node_modules and generated files are skipped.
+     */
+    appRoot: string;
+}
+/**
+ * Vite plugin that injects static `import` statements for custom element
+ * components used in each page/layout/component file.
+ *
+ * Replaces the eager `virtual:cer-components` side-effect import with
+ * per-file static imports, giving Rollup graph edges it needs to
+ * automatically code-split components per page chunk.
+ *
+ * Must be used with `enforce: 'pre'` (already set internally) to ensure
+ * the transform sees the original TypeScript source before esbuild runs.
+ */
+export declare function cerComponentImports(options: CerComponentImportsOptions): Plugin;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jasonshimmy/custom-elements-runtime",
   "description": "A powerful, modern, and lightweight runtime for creating reactive web components with TypeScript",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "type": "module",
   "keywords": [
     "web-components",
@@ -37,19 +37,19 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@testing-library/jest-dom": "^6.9.1",
-    "@types/jsdom": "^28.0.0",
+    "@types/jsdom": "^28.0.1",
     "@typescript-eslint/eslint-plugin": "^8.46.2",
     "@typescript-eslint/parser": "^8.46.2",
-    "@vitest/coverage-v8": "^4.1.0",
-    "cypress": "^15.12.0",
-    "eslint": "^10.0.3",
+    "@vitest/coverage-v8": "^4.1.2",
+    "cypress": "^15.13.0",
+    "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
-    "jsdom": "^29.0.0",
+    "jsdom": "^29.0.1",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.57.1",
-    "vite": "^8.0.0",
+    "typescript-eslint": "^8.57.2",
+    "vite": "^8.0.3",
     "vitest": "^4.0.12"
   },
   "main": "dist/custom-elements-runtime.cjs.js",