@zeus-js/web-c-runtime 0.1.0 → 0.2.0

package/dist/web-c-runtime.d.ts

@@ -5,6 +5,8 @@ export interface ZeusPropMeta {
     type: ZeusPropType;
     reflect?: boolean;
     default?: unknown;
+    serialize?: boolean;
+    deserialize?: boolean;
 }
 export interface ZeusLazyComponentMeta {
     tagName: string;
@@ -17,22 +19,32 @@ export interface ZeusLazyComponentMeta {
         default: ZeusComponentModule;
     }>;
     props: ZeusPropMeta[];
+    methods?: string[];
     /**
      * Whether to render into a ShadowRoot.
      *
      * @default false
      */
     shadow?: boolean;
+    /**
+     * Whether the proxy class participates in browser form association.
+     *
+     * @default false
+     */
+    formAssociated?: boolean;
 }
 export interface HostRef {
     host: HTMLElement;
     meta: ZeusLazyComponentMeta;
+    internals?: ElementInternals;
     connected: boolean;
     loaded: boolean;
     loading?: Promise<void>;
     instance?: ZeusComponentInstance;
     values: Map<string, unknown>;
+    attributeProps: Set<string>;
     reflectingAttrs: Set<string>;
+    pendingFormCallbacks: ZeusFormCallback[];
     readyWaiters: Array<{
         resolve(host: HTMLElement): void;
         reject(error: unknown): void;
@@ -42,6 +54,10 @@ export interface ZeusComponentInstance {
     connected?(): void;
     disconnected?(): void;
     propertyChanged?(name: string, oldValue: unknown, newValue: unknown): void;
+    formAssociated?(form: HTMLFormElement | null): void;
+    formDisabled?(disabled: boolean): void;
+    formReset?(): void;
+    formStateRestore?(state: File | FormData | string | null, mode: 'restore' | 'autocomplete'): void;
     /**
      * Can return Node / Node[] / string.
      * If the component completes rendering itself, it can also return void.
@@ -49,6 +65,19 @@ export interface ZeusComponentInstance {
     render?(): void | string | Node | Node[];
     dispose?(): void;
 }
+type ZeusFormCallback = {
+    type: 'associated';
+    form: HTMLFormElement | null;
+} | {
+    type: 'disabled';
+    disabled: boolean;
+} | {
+    type: 'reset';
+} | {
+    type: 'stateRestore';
+    state: File | FormData | string | null;
+    mode: 'restore' | 'autocomplete';
+};
 export interface ZeusComponentModule {
     createComponent(hostRef: HostRef): ZeusComponentInstance;
 }

package/dist/web-c-runtime.esm-bundler.js

@@ -1,8 +1,29 @@
 /**
-* web-c-runtime v0.1.0
+* web-c-runtime v0.2.0
 * (c) 2026 baicie
 * Released under the MIT License.
 **/
+//#region packages/web-c/web-c-runtime/src/form-callbacks.ts
+function invokeFormCallback(hostRef, callback) {
+	switch (callback.type) {
+		case "associated":
+			var _hostRef$instance, _hostRef$instance$for;
+			(_hostRef$instance = hostRef.instance) === null || _hostRef$instance === void 0 || (_hostRef$instance$for = _hostRef$instance.formAssociated) === null || _hostRef$instance$for === void 0 || _hostRef$instance$for.call(_hostRef$instance, callback.form);
+			return;
+		case "disabled":
+			var _hostRef$instance2, _hostRef$instance2$fo;
+			(_hostRef$instance2 = hostRef.instance) === null || _hostRef$instance2 === void 0 || (_hostRef$instance2$fo = _hostRef$instance2.formDisabled) === null || _hostRef$instance2$fo === void 0 || _hostRef$instance2$fo.call(_hostRef$instance2, callback.disabled);
+			return;
+		case "reset":
+			var _hostRef$instance3, _hostRef$instance3$fo;
+			(_hostRef$instance3 = hostRef.instance) === null || _hostRef$instance3 === void 0 || (_hostRef$instance3$fo = _hostRef$instance3.formReset) === null || _hostRef$instance3$fo === void 0 || _hostRef$instance3$fo.call(_hostRef$instance3);
+			return;
+		case "stateRestore":
+			var _hostRef$instance4, _hostRef$instance4$fo;
+			(_hostRef$instance4 = hostRef.instance) === null || _hostRef$instance4 === void 0 || (_hostRef$instance4$fo = _hostRef$instance4.formStateRestore) === null || _hostRef$instance4$fo === void 0 || _hostRef$instance4$fo.call(_hostRef$instance4, callback.state, callback.mode);
+	}
+}
+//#endregion
 //#region packages/web-c/web-c-runtime/src/host-ref.ts
 const hostRefs = /* @__PURE__ */ new WeakMap();
 function registerHost(host, meta) {
@@ -11,15 +32,27 @@ function registerHost(host, meta) {
 	const hostRef = {
 		host,
 		meta,
+		internals: meta.formAssociated ? attachElementInternals(host) : void 0,
 		connected: false,
 		loaded: false,
 		values: /* @__PURE__ */ new Map(),
+		attributeProps: /* @__PURE__ */ new Set(),
 		reflectingAttrs: /* @__PURE__ */ new Set(),
+		pendingFormCallbacks: [],
 		readyWaiters: []
 	};
 	hostRefs.set(host, hostRef);
 	return hostRef;
 }
+function attachElementInternals(host) {
+	if (typeof host.attachInternals !== "function") return;
+	try {
+		return host.attachInternals();
+	} catch (error) {
+		console.warn("[zeus:web-c] Failed to attach ElementInternals.", error);
+		return;
+	}
+}
 function getHostRef(host) {
 	return hostRefs.get(host);
 }
@@ -53,7 +86,8 @@ function setPropValue(hostRef, prop, value) {
 	const oldValue = getPropValue(hostRef, prop);
 	if (Object.is(oldValue, value)) return;
 	hostRef.values.set(prop.name, value);
-	if (prop.reflect) reflectPropertyToAttribute(hostRef, prop, value);
+	hostRef.attributeProps.delete(prop.name);
+	if (prop.reflect && !prop.serialize) reflectPropertyToAttribute(hostRef, prop, value);
 	if (hostRef.loaded) {
 		var _hostRef$instance, _hostRef$instance$pro;
 		(_hostRef$instance = hostRef.instance) === null || _hostRef$instance === void 0 || (_hostRef$instance$pro = _hostRef$instance.propertyChanged) === null || _hostRef$instance$pro === void 0 || _hostRef$instance$pro.call(_hostRef$instance, prop.name, oldValue, value);
@@ -68,6 +102,7 @@ function syncAttributeToProperty(hostRef, attrName, _oldValue, newValue) {
 	const newPropValue = parseAttributeValue(prop, newValue);
 	if (Object.is(oldPropValue, newPropValue)) return;
 	hostRef.values.set(prop.name, newPropValue);
+	hostRef.attributeProps.add(prop.name);
 	if (hostRef.loaded) {
 		var _hostRef$instance2, _hostRef$instance2$pr;
 		(_hostRef$instance2 = hostRef.instance) === null || _hostRef$instance2 === void 0 || (_hostRef$instance2$pr = _hostRef$instance2.propertyChanged) === null || _hostRef$instance2$pr === void 0 || _hostRef$instance2$pr.call(_hostRef$instance2, prop.name, oldPropValue, newPropValue);
@@ -80,6 +115,7 @@ function applyInitialValues(hostRef) {
 		const attrName = getAttrName(prop);
 		if (attrName && host.hasAttribute(attrName)) {
 			hostRef.values.set(prop.name, parseAttributeValue(prop, host.getAttribute(attrName)));
+			hostRef.attributeProps.add(prop.name);
 			continue;
 		}
 		if ("default" in prop) hostRef.values.set(prop.name, prop.default);
@@ -119,7 +155,7 @@ function findPropByAttrName(hostRef, attrName) {
 function getAttrName(prop) {
 	var _prop$attrName;
 	if (prop.attrName === false) return;
-	if (!isAttributeBackedType(prop.type)) return;
+	if (!isAttributeBackedType(prop.type) && !prop.deserialize) return;
 	return normalizeAttrName((_prop$attrName = prop.attrName) !== null && _prop$attrName !== void 0 ? _prop$attrName : toKebabCase(prop.name));
 }
 function isAttributeBackedType(type) {
@@ -129,6 +165,7 @@ function normalizeAttrName(value) {
 	return value.toLowerCase();
 }
 function parseAttributeValue(prop, value) {
+	if (prop.deserialize) return value;
 	switch (prop.type) {
 		case "boolean": return value !== null;
 		case "number":
@@ -206,6 +243,7 @@ function _initializeComponent() {
 		if (hostRef.loaded) {
 			var _hostRef$instance, _hostRef$instance$con;
 			(_hostRef$instance = hostRef.instance) === null || _hostRef$instance === void 0 || (_hostRef$instance$con = _hostRef$instance.connected) === null || _hostRef$instance$con === void 0 || _hostRef$instance$con.call(_hostRef$instance);
+			flushPendingFormCallbacks(hostRef);
 			return;
 		}
 		if (hostRef.loading) {
@@ -238,6 +276,7 @@ function _doInitializeComponent() {
 		try {
 			var _instance$connected, _instance$render;
 			(_instance$connected = instance.connected) === null || _instance$connected === void 0 || _instance$connected.call(instance);
+			flushPendingFormCallbacks(hostRef);
 			const rendered = (_instance$render = instance.render) === null || _instance$render === void 0 ? void 0 : _instance$render.call(instance);
 			if (rendered !== void 0) mountRenderedOutput(hostRef, rendered);
 			hostRef.loaded = true;
@@ -252,6 +291,12 @@ function _doInitializeComponent() {
 	});
 	return _doInitializeComponent.apply(this, arguments);
 }
+function flushPendingFormCallbacks(hostRef) {
+	while (hostRef.pendingFormCallbacks.length > 0) {
+		invokeFormCallback(hostRef, hostRef.pendingFormCallbacks[0]);
+		hostRef.pendingFormCallbacks.shift();
+	}
+}
 function loadComponentModule(_x3) {
 	return _loadComponentModule.apply(this, arguments);
 }
@@ -331,6 +376,28 @@ function createLazyElementClass(meta) {
 			if (oldValue === newValue) return;
 			syncAttributeToProperty(requireHostRef(this), name, oldValue, newValue);
 		}
+		formAssociatedCallback(form) {
+			dispatchFormCallback(requireHostRef(this), {
+				type: "associated",
+				form
+			});
+		}
+		formDisabledCallback(disabled) {
+			dispatchFormCallback(requireHostRef(this), {
+				type: "disabled",
+				disabled
+			});
+		}
+		formResetCallback() {
+			dispatchFormCallback(requireHostRef(this), { type: "reset" });
+		}
+		formStateRestoreCallback(state, mode) {
+			dispatchFormCallback(requireHostRef(this), {
+				type: "stateRestore",
+				state,
+				mode
+			});
+		}
 		componentOnReady() {
 			const hostRef = requireHostRef(this);
 			if (hostRef.connected && !hostRef.loaded && !hostRef.loading) initializeComponent(hostRef).catch((error) => {
@@ -339,9 +406,37 @@ function createLazyElementClass(meta) {
 			return waitForComponentReady(hostRef);
 		}
 	}
+	ZeusLazyElement.formAssociated = Boolean(meta.formAssociated);
 	installPropertyAccessors(ZeusLazyElement.prototype, meta.props);
+	installMethodProxies(ZeusLazyElement.prototype, meta.methods);
 	return ZeusLazyElement;
 }
+function dispatchFormCallback(hostRef, callback) {
+	if (!hostRef.instance || !hostRef.connected) {
+		hostRef.pendingFormCallbacks.push(callback);
+		return;
+	}
+	invokeFormCallback(hostRef, callback);
+}
+function installMethodProxies(proto, methods) {
+	if (!methods) return;
+	for (const name of methods) {
+		if (name in proto) continue;
+		Object.defineProperty(proto, name, {
+			configurable: true,
+			value: function() {
+				const host = this;
+				const args = Array.prototype.slice.call(arguments);
+				const hostRef = requireHostRef(host);
+				return waitForComponentReady(hostRef).then((readyHost) => {
+					const method = readyHost[name];
+					if (typeof method !== "function") throw new Error(`[zeus:web-c] Method "${name}" is not exposed on <${hostRef.meta.tagName}>.`);
+					return method.apply(readyHost, args);
+				});
+			}
+		});
+	}
+}
 //#endregion
 //#region packages/web-c/web-c-runtime/src/bootstrapLazy.ts
 function bootstrapLazy(components) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeus-js/web-c-runtime",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Zeus Web-C lazy-loading runtime",
   "type": "module",
   "main": "./dist/web-c-runtime.esm-bundler.js",