@useavalon/avalon 0.1.11 → 0.1.12

package/src/build/sidecar-renderer.ts

@@ -1,30 +0,0 @@
-/** Header comment placed at the top of every generated sidecar file. */
-export const SIDECAR_HEADER = "// Auto-generated by avalon — do not edit";
-
-/**
- * Render the full content of a sidecar declaration file.
- *
- * Pure function: takes a props type string (e.g. `"{ count: number }"` or
- * `"Record<string, unknown>"`) and returns the complete file content.
- *
- * The `island` prop is always included so the component can be used with
- * `<Component island={{ condition: 'on:interaction' }} />` in page files.
- * The Vite page-island-transform strips it at build time.
- *
- * The output follows this exact template:
- * ```
- * // Auto-generated by avalon — do not edit
- * import type { ComponentType } from 'preact';
- * import type { IslandDirective } from '@useavalon/avalon';
- * declare const component: ComponentType<PROPS & { island?: IslandDirective }>;
- * export default component;
- * ```
- */
-export function renderSidecarContent(propsType: string): string {
-	return `${SIDECAR_HEADER}
-import type { ComponentType } from 'preact';
-import type { IslandDirective } from '@useavalon/avalon';
-declare const component: ComponentType<${propsType} & { island?: IslandDirective }>;
-export default component;
-`;
-}

package/src/client/adapters/index.js

@@ -1,12 +0,0 @@
-/**
-* Framework HMR Adapters
-* 
-* Exports all framework-specific HMR adapters for easy registration
-*/
-export { ReactHMRAdapter, reactAdapter } from "./react-adapter.js";
-export { PreactHMRAdapter, preactAdapter } from "./preact-adapter.js";
-export { VueHMRAdapter, vueAdapter } from "./vue-adapter.js";
-export { SvelteHMRAdapter, svelteAdapter } from "./svelte-adapter.js";
-export { SolidHMRAdapter, solidAdapter } from "./solid-adapter.js";
-export { LitHMRAdapter, litAdapter } from "./lit-adapter.js";
-export { QwikHMRAdapter, qwikAdapter } from "./qwik-adapter.js";

package/src/client/adapters/index.ts

@@ -1,13 +0,0 @@
-/**
- * Framework HMR Adapters
- * 
- * Exports all framework-specific HMR adapters for easy registration
- */
-
-export { ReactHMRAdapter, reactAdapter } from './react-adapter.ts';
-export { PreactHMRAdapter, preactAdapter } from './preact-adapter.ts';
-export { VueHMRAdapter, vueAdapter } from './vue-adapter.ts';
-export { SvelteHMRAdapter, svelteAdapter } from './svelte-adapter.ts';
-export { SolidHMRAdapter, solidAdapter } from './solid-adapter.ts';
-export { LitHMRAdapter, litAdapter } from './lit-adapter.ts';
-export { QwikHMRAdapter, qwikAdapter } from './qwik-adapter.ts';

package/src/client/adapters/lit-adapter.js

@@ -1,467 +0,0 @@
-/**
-* Lit HMR Adapter
-* 
-* Provides Hot Module Replacement support for Lit components.
-* Handles custom element re-registration and updates all element instances.
-* Preserves element properties across updates.
-* 
-* Requirements: 2.6
-*/
-/// <reference lib="dom" />
-import { BaseFrameworkAdapter } from "../framework-adapter.js";
-/**
-* Lit HMR Adapter
-* 
-* Handles HMR for Lit components by:
-* 1. Re-registering the custom element with a new definition
-* 2. Updating all existing instances of the element
-* 3. Preserving element properties and attributes
-* 
-* Lit components are Web Components (custom elements), so HMR requires:
-* - Undefining the old custom element (if possible)
-* - Defining the new custom element
-* - Updating all instances in the DOM
-* - Preserving reactive properties
-*/
-export class LitHMRAdapter extends BaseFrameworkAdapter {
-	name = "lit";
-	/**
-	* Store element constructors for each island
-	*/
-	elementConstructors = new WeakMap();
-	/**
-	* Store tag names for each island
-	*/
-	tagNames = new WeakMap();
-	/**
-	* Check if a component is a Lit component
-	* 
-	* Lit components are:
-	* - Classes that extend LitElement
-	* - Typically decorated with @customElement
-	* - Have .lit.ts or .lit.js extension (but not always)
-	*/
-	canHandle(component) {
-		if (!component) return false;
-		// Check if it's a class (Lit components are classes)
-		if (typeof component === "function") {
-			const comp = component;
-			// Check for Lit-specific markers
-			// Lit elements may have __litElement marker
-			if (comp.__litElement) {
-				return true;
-			}
-			// Check if it extends LitElement by looking at the prototype chain
-			try {
-				const proto = component.prototype;
-				if (proto) {
-					// Check for Lit-specific methods on prototype
-					if ("render" in proto && "requestUpdate" in proto && "updateComplete" in proto) {
-						return true;
-					}
-					// Check for LitElement in prototype chain
-					let currentProto = proto;
-					while (currentProto && currentProto !== Object.prototype) {
-						const constructor = currentProto.constructor;
-						if (constructor && constructor.name === "LitElement") {
-							return true;
-						}
-						currentProto = Object.getPrototypeOf(currentProto);
-					}
-				}
-			} catch {}
-			// Check for @customElement decorator metadata
-			// The decorator adds metadata to the class
-			if (comp.elementName || comp.tagName) {
-				return true;
-			}
-			// Check function signature - Lit components typically have specific patterns
-			try {
-				const funcStr = component.toString();
-				// Look for Lit-specific patterns
-				if (funcStr.includes("LitElement") || funcStr.includes("customElement") || funcStr.includes("html`") || funcStr.includes("css`") || funcStr.includes("render()") || funcStr.includes("requestUpdate")) {
-					return true;
-				}
-			} catch {}
-		}
-		// Check if it's a Lit component object (wrapped or exported)
-		if (typeof component !== "object") {
-			return false;
-		}
-		const obj = component;
-		// Check for default export pattern
-		if (obj.default && typeof obj.default === "function") {
-			return this.canHandle(obj.default);
-		}
-		// Check for Lit component markers
-		if (obj.__litElement) {
-			return true;
-		}
-		return false;
-	}
-	/**
-	* Preserve Lit element state before HMR update
-	* 
-	* Captures:
-	* - Element properties (reactive properties defined with @property)
-	* - Element attributes
-	* - DOM state (scroll, focus, form values)
-	*/
-	preserveState(island) {
-		try {
-			// Get base DOM state
-			const baseSnapshot = super.preserveState(island);
-			if (!baseSnapshot) return null;
-			// Get Lit-specific data
-			const propsAttr = island.getAttribute("data-props");
-			const capturedProps = propsAttr ? JSON.parse(propsAttr) : {};
-			// Try to get component name from the island
-			const src = island.getAttribute("data-src") || "";
-			const componentName = this.extractComponentName(src);
-			// Get tag name
-			const tagName = island.getAttribute("data-tag-name") || this.tagNames.get(island);
-			// Find the Lit element inside the island
-			const litElement = tagName ? island.querySelector(tagName) : island.querySelector("[data-lit-element]");
-			// Capture element properties and attributes
-			const elementProperties = {};
-			const elementAttributes = {};
-			if (litElement) {
-				// Capture all properties
-				// Lit stores reactive properties on the element instance
-				for (const key in litElement) {
-					if (litElement.hasOwnProperty(key) && !key.startsWith("_")) {
-						try {
-							const value = litElement[key];
-							// Only capture serializable values
-							if (value !== undefined && value !== null && typeof value !== "function" && typeof value !== "symbol") {
-								elementProperties[key] = value;
-							}
-						} catch {}
-					}
-				}
-				// Capture all attributes
-				for (let i = 0; i < litElement.attributes.length; i++) {
-					const attr = litElement.attributes[i];
-					elementAttributes[attr.name] = attr.value;
-				}
-			}
-			const litSnapshot = {
-				...baseSnapshot,
-				framework: "lit",
-				data: {
-					componentName,
-					tagName: tagName || undefined,
-					capturedProps,
-					elementProperties,
-					elementAttributes
-				}
-			};
-			return litSnapshot;
-		} catch (error) {
-			console.warn("Failed to preserve Lit state:", error);
-			return null;
-		}
-	}
-	/**
-	* Update Lit component with HMR
-	* 
-	* This method handles custom element re-registration:
-	* 1. Extract the tag name from the component or island
-	* 2. Find all instances of the element in the DOM
-	* 3. Preserve their properties and attributes
-	* 4. Undefine the old custom element (if possible)
-	* 5. Define the new custom element
-	* 6. Update all instances with the new definition
-	* 7. Restore properties and attributes
-	*/
-	async update(island, newComponent, props) {
-		if (!this.canHandle(newComponent)) {
-			throw new Error("Component is not a valid Lit component");
-		}
-		// Extract the actual component class
-		let ElementClass;
-		if (typeof newComponent === "object" && newComponent !== null) {
-			const obj = newComponent;
-			if (obj.default && typeof obj.default === "function") {
-				ElementClass = obj.default;
-			} else {
-				throw new Error("Lit component object must have a default export");
-			}
-		} else if (typeof newComponent === "function") {
-			ElementClass = newComponent;
-		} else {
-			throw new Error("Invalid Lit component type");
-		}
-		try {
-			// Determine the tag name
-			// Priority: data-tag-name attribute > elementName property > derive from class name
-			let tagName = island.getAttribute("data-tag-name");
-			if (!tagName) {
-				// Try to get from the class
-				tagName = ElementClass.elementName;
-			}
-			if (!tagName) {
-				// Derive from class name (convert PascalCase to kebab-case)
-				tagName = ElementClass.name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-			}
-			if (!tagName || !tagName.includes("-")) {
-				throw new Error("Invalid custom element tag name: " + tagName);
-			}
-			// Store tag name for future updates
-			this.tagNames.set(island, tagName);
-			island.setAttribute("data-tag-name", tagName);
-			// Find all instances of this element in the island
-			const elements = Array.from(island.querySelectorAll(tagName));
-			// If no elements exist, create one
-			if (elements.length === 0) {
-				// Check if the custom element is already defined
-				const existingDefinition = customElements.get(tagName);
-				if (!existingDefinition) {
-					// Define the custom element
-					customElements.define(tagName, ElementClass);
-				} else if (existingDefinition !== ElementClass) {
-					// Element is already defined with a different class
-					// We need to re-register it
-					await this.reregisterCustomElement(tagName, ElementClass);
-				}
-				// Create a new element
-				const newElement = document.createElement(tagName);
-				// Set properties from props
-				Object.entries(props).forEach(([key, value]) => {
-					try {
-						newElement[key] = value;
-					} catch (error) {
-						console.warn(`Failed to set property ${key} on Lit element:`, error);
-					}
-				});
-				// Append to island
-				island.appendChild(newElement);
-				// Store constructor
-				this.elementConstructors.set(island, ElementClass);
-				// Mark as hydrated
-				island.setAttribute("data-hydrated", "true");
-				island.setAttribute("data-hydration-status", "success");
-				return;
-			}
-			// Update existing elements
-			// First, check if we need to re-register the custom element
-			const existingDefinition = customElements.get(tagName);
-			if (existingDefinition && existingDefinition !== ElementClass) {
-				// Re-register the custom element with the new definition
-				await this.reregisterCustomElement(tagName, ElementClass);
-				// After re-registration, we need to replace all existing elements
-				// because they're instances of the old class
-				for (const oldElement of elements) {
-					// Preserve state
-					const properties = {};
-					const attributes = {};
-					// Capture properties
-					for (const key in oldElement) {
-						if (oldElement.hasOwnProperty(key) && !key.startsWith("_")) {
-							try {
-								const value = oldElement[key];
-								if (value !== undefined && value !== null && typeof value !== "function" && typeof value !== "symbol") {
-									properties[key] = value;
-								}
-							} catch {}
-						}
-					}
-					// Capture attributes
-					for (let i = 0; i < oldElement.attributes.length; i++) {
-						const attr = oldElement.attributes[i];
-						attributes[attr.name] = attr.value;
-					}
-					// Create new element
-					const newElement = document.createElement(tagName);
-					// Restore attributes
-					Object.entries(attributes).forEach(([name, value]) => {
-						newElement.setAttribute(name, value);
-					});
-					// Restore properties
-					Object.entries(properties).forEach(([key, value]) => {
-						try {
-							newElement[key] = value;
-						} catch (error) {
-							console.warn(`Failed to restore property ${key}:`, error);
-						}
-					});
-					// Replace old element with new element
-					oldElement.parentNode?.replaceChild(newElement, oldElement);
-				}
-			} else if (!existingDefinition) {
-				// Define the custom element for the first time
-				customElements.define(tagName, ElementClass);
-				// Trigger update on all elements
-				for (const element of elements) {
-					if (element.requestUpdate) {
-						element.requestUpdate();
-					}
-				}
-			} else {
-				// Same class, just trigger updates
-				for (const element of elements) {
-					// Update properties from props
-					Object.entries(props).forEach(([key, value]) => {
-						try {
-							element[key] = value;
-						} catch (error) {
-							console.warn(`Failed to update property ${key}:`, error);
-						}
-					});
-					// Request update
-					if (element.requestUpdate) {
-						element.requestUpdate();
-					}
-				}
-			}
-			// Store constructor
-			this.elementConstructors.set(island, ElementClass);
-			// Mark as hydrated
-			island.setAttribute("data-hydrated", "true");
-			island.setAttribute("data-hydration-status", "success");
-		} catch (error) {
-			console.error("Lit HMR update failed:", error);
-			island.setAttribute("data-hydration-status", "error");
-			throw error;
-		}
-	}
-	/**
-	* Re-register a custom element with a new definition
-	* 
-	* Custom elements cannot be undefined once defined, so we need to:
-	* 1. Create a new tag name (with a version suffix)
-	* 2. Define the new element with the new tag name
-	* 3. Update all references to use the new tag name
-	* 
-	* Alternative approach (used here):
-	* 1. Use a wrapper element that delegates to the actual element
-	* 2. Update the wrapper to use the new element class
-	*/
-	async reregisterCustomElement(tagName, ElementClass) {
-		// Unfortunately, custom elements cannot be truly undefined once defined
-		// The best we can do is define a new version with a suffix
-		// However, for HMR purposes, we can use a different approach:
-		// We'll just replace all instances of the old element with new instances
-		// This is handled in the update() method above
-		// For now, we'll just log a warning
-		console.warn(`Custom element ${tagName} is already defined. ` + `Replacing all instances with new definition.`);
-		// Note: In a production HMR system, you might want to:
-		// 1. Use a versioned tag name (e.g., my-element-v2)
-		// 2. Use a proxy element that delegates to the actual element
-		// 3. Use a custom element registry that supports re-registration
-		// For this implementation, we rely on replacing element instances
-		// which is handled in the update() method
-	}
-	/**
-	* Restore Lit element state after HMR update
-	* 
-	* Restores:
-	* - Element properties
-	* - Element attributes
-	* - DOM state (scroll, focus, form values)
-	*/
-	restoreState(island, state) {
-		try {
-			// Restore DOM state (scroll, focus, form values)
-			super.restoreState(island, state);
-			// Restore Lit-specific state
-			const litState = state;
-			const tagName = litState.data.tagName;
-			if (tagName) {
-				const litElement = island.querySelector(tagName);
-				if (litElement) {
-					// Restore element properties
-					if (litState.data.elementProperties) {
-						Object.entries(litState.data.elementProperties).forEach(([key, value]) => {
-							try {
-								litElement[key] = value;
-							} catch (error) {
-								console.warn(`Failed to restore property ${key}:`, error);
-							}
-						});
-					}
-					// Restore element attributes
-					if (litState.data.elementAttributes) {
-						Object.entries(litState.data.elementAttributes).forEach(([name, value]) => {
-							try {
-								litElement.setAttribute(name, value);
-							} catch (error) {
-								console.warn(`Failed to restore attribute ${name}:`, error);
-							}
-						});
-					}
-					// Request update to apply changes
-					if (litElement.requestUpdate) {
-						litElement.requestUpdate();
-					}
-				}
-			}
-		} catch (error) {
-			console.warn("Failed to restore Lit state:", error);
-		}
-	}
-	/**
-	* Handle errors during Lit HMR update
-	* 
-	* Provides Lit-specific error handling with helpful messages
-	*/
-	handleError(island, error) {
-		console.error("Lit HMR error:", error);
-		// Use base error handling
-		super.handleError(island, error);
-		// Add Lit-specific error information
-		const errorIndicator = island.querySelector(".hmr-error-indicator");
-		if (errorIndicator) {
-			const errorMessage = error.message;
-			// Provide helpful hints for common Lit errors
-			let hint = "";
-			if (errorMessage.includes("custom element") || errorMessage.includes("define")) {
-				hint = " (Hint: Check that your element has a valid tag name with a hyphen)";
-			} else if (errorMessage.includes("tag name")) {
-				hint = " (Hint: Custom element tag names must contain a hyphen)";
-			} else if (errorMessage.includes("property") || errorMessage.includes("attribute")) {
-				hint = " (Hint: Check @property decorators and attribute names)";
-			} else if (errorMessage.includes("render")) {
-				hint = " (Hint: Check the render() method for errors)";
-			} else if (errorMessage.includes("shadow")) {
-				hint = " (Hint: Check Shadow DOM usage and styles)";
-			}
-			errorIndicator.textContent = `Lit HMR Error: ${errorMessage}${hint}`;
-		}
-	}
-	/**
-	* Extract component name from source path
-	* Used for debugging and error messages
-	*/
-	extractComponentName(src) {
-		const parts = src.split("/");
-		const filename = parts[parts.length - 1];
-		return filename.replace(/\.lit\.(ts|js)$/, "").replace(/\.(ts|js)$/, "");
-	}
-	/**
-	* Clean up Lit element when island is removed
-	* This should be called when an island is unmounted
-	*/
-	unmount(island) {
-		try {
-			const tagName = this.tagNames.get(island);
-			if (tagName) {
-				// Find all elements and disconnect them
-				const elements = island.querySelectorAll(tagName);
-				elements.forEach((element) => {
-					// Lit elements clean up automatically when disconnected
-					// but we can help by removing them from the DOM
-					element.remove();
-				});
-				this.tagNames.delete(island);
-			}
-			this.elementConstructors.delete(island);
-		} catch (error) {
-			console.warn("Failed to unmount Lit element:", error);
-		}
-	}
-}
-/**
-* Create and export a singleton instance of the Lit HMR adapter
-*/
-export const litAdapter = new LitHMRAdapter();