@zeus-js/output-wc 0.1.0-beta.1 → 0.1.0-beta.3

package/dist/output-wc.cjs.prod.js

@@ -1,5 +1,5 @@
 /**
-* output-wc v0.1.0-beta.1
+* output-wc v0.1.0-beta.3
 * (c) 2026 baicie
 * Released under the MIT License.
 **/
@@ -176,6 +176,136 @@ function getVirtualIndexId() {
 	return "zeus:wc:index";
 }
 //#endregion
+//#region packages/web-c/output-wc/src/generateLazyEntry.ts
+function generateLazyEntry(options) {
+	const { component, outPath, sourceImport } = options;
+	const source = sourceImport !== null && sourceImport !== void 0 ? sourceImport : toRelativeImport(component.source, outPath);
+	return [
+		`import { mountElementDefinition } from "@zeus-js/runtime-dom";`,
+		`import { ${component.exportName} } from ${JSON.stringify(source)};`,
+		"",
+		`export function createComponent(hostRef) {`,
+		`  let mounted;`,
+		`  const mountState = {};`,
+		"",
+		`  return {`,
+		`    connected() {`,
+		`      if (mounted) return;`,
+		"",
+		`      mounted = mountElementDefinition(`,
+		`        ${component.exportName},`,
+		`        hostRef.host,`,
+		`        hostRef.values,`,
+		`        mountState,`,
+		`      );`,
+		`    },`,
+		"",
+		`    disconnected() {`,
+		`      mounted?.dispose();`,
+		`      mounted = undefined;`,
+		`    },`,
+		"",
+		`    propertyChanged(name, oldValue, newValue) {`,
+		`      mounted?.propertyChanged(name, oldValue, newValue);`,
+		`    },`,
+		`  };`,
+		`}`,
+		"",
+		`export default { createComponent };`,
+		""
+	].join("\n");
+}
+function toRelativeImport(source, outPath) {
+	const sourceParts = normalizePath(source).split("/");
+	const outParts = normalizePath(outPath).split("/");
+	let common = 0;
+	for (let i = 0; i < Math.min(sourceParts.length, outParts.length); i++) if (sourceParts[i] === outParts[i]) common++;
+	else break;
+	return [...outParts.slice(common).map(() => ".."), ...sourceParts.slice(common)].join("/");
+}
+//#endregion
+//#region packages/web-c/output-wc/src/generateLazyManifest.ts
+function generateLazyManifest(options) {
+	const { components, getEntryFileName } = options;
+	return `export const components = [
+${components.map((component) => {
+		var _component$runtimePro, _component$meta$shado, _component$meta;
+		const entryFile = getEntryFileName(component.tag).replace(/\\/g, "/");
+		const props = generatePropsArray((_component$runtimePro = component.runtimeProps) !== null && _component$runtimePro !== void 0 ? _component$runtimePro : component.props);
+		const importPath = entryFile.startsWith(".") ? JSON.stringify(entryFile) : JSON.stringify(`./${entryFile}`);
+		return `  {
+    tagName: ${JSON.stringify(component.tag)},
+    shadow: ${(_component$meta$shado = (_component$meta = component.meta) === null || _component$meta === void 0 ? void 0 : _component$meta.shadow) !== null && _component$meta$shado !== void 0 ? _component$meta$shado : false},
+    load: () => import(${importPath}),
+    props: ${props},
+  }`;
+	}).join(",\n")}
+];
+`;
+}
+function generatePropsArray(props) {
+	const entries = Object.entries(props);
+	if (entries.length === 0) return "[]";
+	return `[\n${entries.map(([name, prop]) => {
+		const parts = [`name: ${JSON.stringify(name)}`];
+		if (!isAttributeBackedType(prop.type) || prop.attr === false) parts.push("attrName: false");
+		else {
+			var _prop$attr;
+			const attrName = (_prop$attr = prop.attr) !== null && _prop$attr !== void 0 ? _prop$attr : toKebabCase(name);
+			if (attrName !== toKebabCase(name)) parts.push(`attrName: ${JSON.stringify(attrName)}`);
+		}
+		parts.push(`type: ${JSON.stringify(prop.type)}`);
+		if (prop.reflect && isAttributeBackedType(prop.type)) parts.push("reflect: true");
+		return `      { ${parts.join(", ")} }`;
+	}).join(",\n")}\n    ]`;
+}
+function isAttributeBackedType(type) {
+	return type === "string" || type === "number" || type === "boolean";
+}
+function toKebabCase(value) {
+	return value.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
+}
+//#endregion
+//#region packages/web-c/output-wc/src/generateLoader.ts
+function generateLoader() {
+	return `import { bootstrapLazy } from "@zeus-js/web-c-runtime";
+import { components } from "./components.manifest.js";
+
+let defined = false;
+
+export function defineCustomElements() {
+  if (defined) {
+    return;
+  }
+
+  if (typeof customElements === "undefined") {
+    return;
+  }
+
+  bootstrapLazy(components);
+
+  defined = true;
+}
+
+export const defineLazyElements = defineCustomElements;
+`;
+}
+function generateAutoEntry() {
+	return `import { defineCustomElements } from "./loader.js";
+
+defineCustomElements();
+
+export {};
+`;
+}
+function generateLazyIndex() {
+	return `export {
+  defineCustomElements,
+  defineLazyElements,
+} from "./loader.js";
+`;
+}
+//#endregion
 //#region packages/web-c/output-wc/src/generateManifest.ts
 function generateZeusComponentsManifest(manifest) {
 	return `${JSON.stringify(manifest, null, 2)}\n`;
@@ -183,17 +313,21 @@ function generateZeusComponentsManifest(manifest) {
 //#endregion
 //#region packages/web-c/output-wc/src/index.ts
 function wc(options = {}) {
-	var _options$outDir, _options$stripPrefix, _options$manifestFile, _options$customElemen, _options$dts, _options$jsxDts, _options$index, _options$warnOnFileNa;
+	var _options$register, _options$outDir, _options$stripPrefix, _options$manifestFile, _options$customElemen, _options$dts, _options$jsxDts, _options$index, _options$warnOnFileNa, _options$auto, _options$entryFileNam;
+	const registerMode = (_options$register = options.register) !== null && _options$register !== void 0 ? _options$register : "lazy";
 	const normalized = {
 		outDir: (_options$outDir = options.outDir) !== null && _options$outDir !== void 0 ? _options$outDir : "wc",
 		stripPrefix: (_options$stripPrefix = options.stripPrefix) !== null && _options$stripPrefix !== void 0 ? _options$stripPrefix : false,
 		fileName: options.fileName,
-		manifestFile: (_options$manifestFile = options.manifestFile) !== null && _options$manifestFile !== void 0 ? _options$manifestFile : "zeus.components.json",
-		customElementsFile: (_options$customElemen = options.customElementsFile) !== null && _options$customElemen !== void 0 ? _options$customElemen : "custom-elements.json",
-		dts: (_options$dts = options.dts) !== null && _options$dts !== void 0 ? _options$dts : "auto",
-		jsxDts: (_options$jsxDts = options.jsxDts) !== null && _options$jsxDts !== void 0 ? _options$jsxDts : "auto",
+		manifestFile: registerMode === "lazy" ? false : (_options$manifestFile = options.manifestFile) !== null && _options$manifestFile !== void 0 ? _options$manifestFile : "zeus.components.json",
+		customElementsFile: registerMode === "lazy" ? false : (_options$customElemen = options.customElementsFile) !== null && _options$customElemen !== void 0 ? _options$customElemen : "custom-elements.json",
+		dts: (_options$dts = options.dts) !== null && _options$dts !== void 0 ? _options$dts : true,
+		jsxDts: (_options$jsxDts = options.jsxDts) !== null && _options$jsxDts !== void 0 ? _options$jsxDts : true,
 		index: (_options$index = options.index) !== null && _options$index !== void 0 ? _options$index : true,
-		warnOnFileNameCollision: (_options$warnOnFileNa = options.warnOnFileNameCollision) !== null && _options$warnOnFileNa !== void 0 ? _options$warnOnFileNa : true
+		warnOnFileNameCollision: (_options$warnOnFileNa = options.warnOnFileNameCollision) !== null && _options$warnOnFileNa !== void 0 ? _options$warnOnFileNa : true,
+		register: registerMode,
+		auto: (_options$auto = options.auto) !== null && _options$auto !== void 0 ? _options$auto : true,
+		entryFileName: (_options$entryFileNam = options.entryFileName) !== null && _options$entryFileNam !== void 0 ? _options$entryFileNam : ((tag) => `${tag}.entry`)
 	};
 	let _outDir = normalized.outDir;
 	return {
@@ -208,7 +342,32 @@ function wc(options = {}) {
 		},
 		buildStart(ctx) {
 			if (!ctx.manifest) return;
-			checkFileNameCollisions(ctx.manifest.components, normalized, { warn: ctx.warn });
+			if (normalized.register === "lazy") for (const component of ctx.manifest.components) {
+				var _component$runtimePro, _component$runtimePro2;
+				const diagnostics = (_component$runtimePro = component.runtimePropsDiagnostics) !== null && _component$runtimePro !== void 0 ? _component$runtimePro : [];
+				if (diagnostics.length > 0) ctx.error([`[zeus-output-wc] <${component.tag}> cannot be emitted with register:"lazy" because its runtime props are not statically analyzable.`, ...diagnostics.map((message) => `- ${message}`)].join("\n"));
+				const runtimeProps = (_component$runtimePro2 = component.runtimeProps) !== null && _component$runtimePro2 !== void 0 ? _component$runtimePro2 : {};
+				for (const [name, prop] of Object.entries(runtimeProps)) {
+					if (isAttributeBackedRuntimeProp(prop.type)) continue;
+					if (prop.attr !== void 0 && prop.attr !== false) ctx.error([
+						`[zeus-output-wc] <${component.tag}> prop "${name}" cannot use attr:${JSON.stringify(prop.attr)} with register:"lazy".`,
+						"Lazy Web-C only supports attributes for string, number and boolean props.",
+						"Use attr:false and pass object/array/function values as properties instead."
+					].join("\n"));
+					if (prop.reflect) ctx.error([
+						`[zeus-output-wc] <${component.tag}> prop "${name}" cannot use reflect:true with register:"lazy".`,
+						"Lazy Web-C only reflects string, number and boolean props.",
+						"Use a string/number/boolean prop or remove reflect:true."
+					].join("\n"));
+				}
+			}
+			checkFileNameCollisions(ctx.manifest.components, {
+				getFileName: (tag) => {
+					if (normalized.register === "lazy") return getLazyEntryFileName(normalized.entryFileName, tag);
+					return normalizeFileName(tag, normalized.stripPrefix, normalized.fileName);
+				},
+				warnOnFileNameCollision: normalized.warnOnFileNameCollision
+			}, { warn: ctx.warn });
 		},
 		virtualModules(ctx) {
 			if (!ctx.manifest) return [];
@@ -222,7 +381,55 @@ function wc(options = {}) {
 				if (hasOutputs) return ctx.outputs.join("wc", fileName);
 				return node_path.default.posix.join(_outDir, fileName);
 			};
-			for (const component of ctx.manifest.components) {
+			const isLazy = normalized.register === "lazy";
+			if (isLazy) {
+				modules.push({
+					id: "zeus:wc:components.manifest",
+					fileName: joinPath("components.manifest.js"),
+					code: generateLazyManifest({
+						components: ctx.manifest.components,
+						getEntryFileName: (tag) => getLazyEntryFileName(normalized.entryFileName, tag)
+					})
+				});
+				modules.push({
+					id: "zeus:wc:loader",
+					fileName: joinPath("loader.js"),
+					code: generateLoader()
+				});
+				if (normalized.auto) modules.push({
+					id: "zeus:wc:auto",
+					fileName: joinPath("auto.js"),
+					code: generateAutoEntry()
+				});
+			}
+			for (const component of ctx.manifest.components) if (isLazy) {
+				/**
+				* Compatibility module consumed by Vue / React wrappers.
+				*
+				* It only registers lazy Proxy Elements.
+				* It does not import the real component implementation.
+				*/
+				modules.push({
+					id: getVirtualComponentId(component),
+					code: `
+import { defineCustomElements } from "zeus:wc:loader";
+
+defineCustomElements();
+
+export {};
+`.trimStart()
+				});
+				const fileName = joinPath(getLazyEntryFileName(normalized.entryFileName, component.tag));
+				modules.push({
+					id: `zeus:wc:entry:${component.tag}`,
+					fileName,
+					code: generateLazyEntry({
+						component,
+						outPath: fileName,
+						sourceImport: toAbsoluteImportPath(ctx.root, component.source)
+					})
+				});
+			} else {
 				const fileName = joinPath(getFileName(component.tag));
 				modules.push({
 					id: getVirtualComponentId(component),
@@ -233,7 +440,7 @@ function wc(options = {}) {
 					})
 				});
 			}
-			if (normalized.index) modules.push({
+			if (normalized.index && !isLazy) modules.push({
 				id: getVirtualIndexId(),
 				fileName: joinPath("index.js"),
 				code: generateWCIndex({
@@ -241,16 +448,18 @@ function wc(options = {}) {
 					getFileName
 				})
 			});
+			if (isLazy && normalized.index) modules.push({
+				id: getVirtualIndexId(),
+				fileName: joinPath("index.js"),
+				code: generateLazyIndex()
+			});
 			return modules;
 		},
 		generateBundle(ctx) {
 			if (!ctx.manifest) return [];
 			const files = [];
-			if (normalized.manifestFile) files.push({
-				type: "asset",
-				fileName: normalized.manifestFile,
-				source: generateZeusComponentsManifest(ctx.manifest)
-			});
+			const dts = (0, _zeus_js_bundler_plugin.resolvePluginDts)(normalized.dts, ctx);
+			const jsxDts = (0, _zeus_js_bundler_plugin.resolvePluginDts)(normalized.jsxDts, ctx);
 			const hasOutputs = ctx.outputs.has("wc");
 			const getFileName = (tag) => {
 				if (hasOutputs) return ctx.outputs.getFileName("wc", tag);
@@ -260,7 +469,32 @@ function wc(options = {}) {
 				if (hasOutputs) return ctx.outputs.join("wc", fileName);
 				return node_path.default.posix.join(_outDir, fileName);
 			};
-			if (normalized.customElementsFile) files.push({
+			const isLazy = normalized.register === "lazy";
+			if (isLazy) {
+				if (dts) {
+					const loaderDts = (0, _zeus_js_component_dts.generateLoaderDts)(ctx.manifest);
+					files.push({
+						type: "asset",
+						fileName: joinPath("loader.d.ts"),
+						source: loaderDts
+					});
+					if (normalized.index) files.push({
+						type: "asset",
+						fileName: joinPath("index.d.ts"),
+						source: loaderDts
+					});
+				}
+				if (jsxDts) files.push({
+					type: "asset",
+					fileName: joinPath("types/jsx.d.ts"),
+					source: (0, _zeus_js_component_dts.generateWCJsxDts)(ctx.manifest)
+				});
+			} else if (normalized.manifestFile) files.push({
+				type: "asset",
+				fileName: normalized.manifestFile,
+				source: generateZeusComponentsManifest(ctx.manifest)
+			});
+			if (!isLazy && normalized.customElementsFile) files.push({
 				type: "asset",
 				fileName: normalized.customElementsFile,
 				source: generateCustomElementsJson({
@@ -268,9 +502,7 @@ function wc(options = {}) {
 					getModulePath: (component) => joinPath(getFileName(component.tag))
 				})
 			});
-			const dts = (0, _zeus_js_bundler_plugin.resolvePluginDts)(normalized.dts, ctx);
-			const jsxDts = (0, _zeus_js_bundler_plugin.resolvePluginDts)(normalized.jsxDts, ctx);
-			if (dts || jsxDts) {
+			if (!isLazy && (dts || jsxDts)) {
 				const dtsFiles = (0, _zeus_js_component_dts.generateWCDtsFiles)(ctx.manifest, {
 					outDir: _outDir,
 					stripPrefix: normalized.stripPrefix,
@@ -299,12 +531,22 @@ function normalizeFileName(tag, stripPrefix, fileName) {
 	if (!name.endsWith(".js")) name = `${name}.js`;
 	return name;
 }
+function normalizeLazyEntryFileName(fileName) {
+	const normalized = fileName.replace(/\\/g, "/");
+	return normalized.endsWith(".js") ? normalized : `${normalized}.js`;
+}
+function getLazyEntryFileName(entryFileName, tag) {
+	return normalizeLazyEntryFileName(entryFileName(tag));
+}
+function isAttributeBackedRuntimeProp(type) {
+	return type === "string" || type === "number" || type === "boolean";
+}
 function checkFileNameCollisions(components, options, reporter) {
 	if (options.warnOnFileNameCollision === false) return;
 	const map = /* @__PURE__ */ new Map();
 	for (const component of components) {
 		var _map$get;
-		const fileName = normalizeFileName(component.tag, options.stripPrefix, options.fileName);
+		const fileName = options.getFileName(component.tag);
 		const list = (_map$get = map.get(fileName)) !== null && _map$get !== void 0 ? _map$get : [];
 		list.push(component);
 		map.set(fileName, list);

package/dist/output-wc.d.ts

@@ -1,5 +1,6 @@
 import { DtsMode, ZeusComponentPlugin } from '@zeus-js/bundler-plugin';
 
+type WebCRegisterMode = 'lazy' | 'side-effect';
 export interface OutputWCOptions {
     /**
      * Web Component output directory.
@@ -35,13 +36,13 @@ export interface OutputWCOptions {
     /**
      * Generate WC d.ts.
      *
-     * @default 'auto'
+     * @default true
      */
     dts?: DtsMode;
     /**
      * Generate JSX IntrinsicElements d.ts.
      *
-     * @default 'auto'
+     * @default true
      */
     jsxDts?: DtsMode;
     /**
@@ -56,6 +57,30 @@ export interface OutputWCOptions {
      * @default true
      */
     warnOnFileNameCollision?: boolean;
+    /**
+     * lazy:
+     *   Default. Generates Stencil-style lazy loader.
+     *   On startup, registers lightweight ProxyClass; loads real component entry
+     *   only when the element is connected to the DOM.
+     *
+     * side-effect:
+     *   Immediately registers full components on import.
+     *   Compatible with legacy behavior; not recommended as default.
+     */
+    register?: WebCRegisterMode;
+    /**
+     * Whether to generate the auto.js entry (lazy mode).
+     *
+     * @default true
+     */
+    auto?: boolean;
+    /**
+     * File name for lazy mode entry chunks.
+     * Receives the tag name, should return the file name (without .js).
+     *
+     * @default (tag) => `${tag}.entry`
+     */
+    entryFileName?: (tag: string) => string;
 }
 
 export declare function wc(options?: OutputWCOptions): ZeusComponentPlugin;